kinetic-core 0.2.0

Core daemon primitives, VDF management, and network utilities for the Kinetic Network.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

#![allow(rustdoc::redundant_explicit_links)]
//! # kinetic-core
//!
//! The foundational shared kernel for the Kinetic decentralized naming network.
//!
//! `kinetic-core` contains the core models, protocol constants, cryptographic
//! state machines, error hierarchies, and common I/O utilities used across all Kinetic
//! binaries and sub-crates.
//!
//! ## Architecture & Module Map
//!
//! - **[`config`]** — Daemon configuration structures ([`KineticConfig`](config::KineticConfig)) and network port defaults.
//! - **[`types`]** — Shared wire-format types ([`DnsZone`](types::DnsZone), [`DnsRecord`](types::DnsRecord), [`Commitment`](types::Commitment), [`VdfProof`](types::VdfProof)) and name normalization rules.
//! - **[`error`]** — Unified error logbook ([`KineticError`](error::KineticError)), domain errors ([`ResolutionError`](error::ResolutionError), [`PublishError`](error::PublishError), [`RegistrationError`](error::RegistrationError)), and stable error codes.
//! - **[`traits`]** — Core abstraction traits ([`StorageEngine`](traits::StorageEngine) and [`VdfEngine`](traits::VdfEngine)).
//! - **[`governance`]** — Council state machine and parameter rulebooks governing privileged protocol actions.
//! - **[`consensus_math`]** — Deterministic math routines for VDF difficulty scaling, name-length pricing, and grace period calculations.
//! - **[`drand`]** — Client interface for the drand distributed randomness beacon used in time-bound operations.
//! - **[`net`]** — Network security primitives, IP classification, and SSRF prevention guards.
//! - **[`shutdown`]** — Cross-platform graceful shutdown listeners.

//! - **[`api_error`]** *(Non-WASM)* — HTTP status code mapping and Axum-compatible API error responses ([`ApiError`](api_error::ApiError)).
//! - **[`request_id`]** *(Non-WASM)* — Idempotency key generators for daemon API requests.

#![deny(missing_docs)]

/// HTTP API error types compatible with axum and tower response extractors.
#[cfg(not(target_arch = "wasm32"))]
pub mod api_error;
/// Config file loading, default values, and port constants for all Kinetic binaries.
pub mod config;
/// Mathematical helpers for consensus: VDF difficulty scaling and name-length fees.
pub mod consensus_math;
/// Global protocol constants.
pub mod constants;
/// drand beacon client for epoch-bound randomness and Sybil-resistance.
pub mod drand;
/// Unified error taxonomy: [`KineticError`](error::KineticError), [`ResolutionError`](error::ResolutionError), [`PublishError`](error::PublishError), and [`RegistrationError`](error::RegistrationError).
pub mod error;
/// Protocol governance: council proposals, voting, and parameter updates.
pub mod governance;

/// Network security utilities for SSRF prevention.
pub mod net;
/// Idempotency key helpers for deduplicating daemon API requests.
#[cfg(not(target_arch = "wasm32"))]
pub mod request_id;
/// Cross-platform graceful shutdown signal listener.
pub mod shutdown;
/// Core trait definitions: [`StorageEngine`](traits::StorageEngine) and [`VdfEngine`](traits::VdfEngine).
pub mod traits;
/// Shared wire-format types for P2P messages, DNS zones, and name records.
pub mod types;
#[cfg(not(target_arch = "wasm32"))]
/// HTTP API error response wrapper ([`ApiError`](api_error::ApiError)) for Axum web handlers.
#[cfg(not(target_arch = "wasm32"))]
pub use api_error::ApiError;

/// Primary protocol error taxonomy re-exported at crate root:
/// - [`KineticError`]: Top-level unified error enum.
/// - [`PublishError`]: Record publication failures (`KIN-PUB-*`).
/// - [`RegistrationError`]: Name registration failures (`KIN-REG-*`).
/// - [`ResolutionError`]: DHT name resolution failures (`KIN-RES-*`).
/// - [`RecordRejectReason`]: Storage engine rejection codes.
/// - [`VdfRejectReason`]: VDF proof validation rejection reasons.
/// - [`Severity`]: Logging & monitoring alert severity classifier (`Info`, `Warning`, `Error`, `Critical`).
pub use error::{
    KineticError, PublishError, RecordRejectReason, RegistrationError, ResolutionError, Severity,
    VdfRejectReason,
};