kinetic_core/lib.rs
1#![allow(rustdoc::redundant_explicit_links)]
2//! # kinetic-core
3//!
4//! The foundational shared kernel for the Kinetic decentralized naming network.
5//!
6//! `kinetic-core` contains the core models, protocol constants, cryptographic
7//! state machines, error hierarchies, and common I/O utilities used across all Kinetic
8//! binaries and sub-crates.
9//!
10//! ## Architecture & Module Map
11//!
12//! - **[`config`]** — Daemon configuration structures ([`KineticConfig`](config::KineticConfig)) and network port defaults.
13//! - **[`types`]** — Shared wire-format types ([`DnsZone`](types::DnsZone), [`DnsRecord`](types::DnsRecord), [`Commitment`](types::Commitment), [`VdfProof`](types::VdfProof)) and name normalization rules.
14//! - **[`error`]** — Unified error logbook ([`KineticError`](error::KineticError)), domain errors ([`ResolutionError`](error::ResolutionError), [`PublishError`](error::PublishError), [`RegistrationError`](error::RegistrationError)), and stable error codes.
15//! - **[`traits`]** — Core abstraction traits ([`StorageEngine`](traits::StorageEngine) and [`VdfEngine`](traits::VdfEngine)).
16//! - **[`governance`]** — Council state machine and parameter rulebooks governing privileged protocol actions.
17//! - **[`consensus_math`]** — Deterministic math routines for VDF difficulty scaling, name-length pricing, and grace period calculations.
18//! - **[`drand`]** — Client interface for the drand distributed randomness beacon used in time-bound operations.
19//! - **[`net`]** — Network security primitives, IP classification, and SSRF prevention guards.
20//! - **[`shutdown`]** — Cross-platform graceful shutdown listeners.
21
22//! - **[`api_error`]** *(Non-WASM)* — HTTP status code mapping and Axum-compatible API error responses ([`ApiError`](api_error::ApiError)).
23//! - **[`request_id`]** *(Non-WASM)* — Idempotency key generators for daemon API requests.
24
25#![deny(missing_docs)]
26
27/// HTTP API error types compatible with axum and tower response extractors.
28#[cfg(not(target_arch = "wasm32"))]
29pub mod api_error;
30/// Config file loading, default values, and port constants for all Kinetic binaries.
31pub mod config;
32/// Mathematical helpers for consensus: VDF difficulty scaling and name-length fees.
33pub mod consensus_math;
34/// Global protocol constants.
35pub mod constants;
36/// drand beacon client for epoch-bound randomness and Sybil-resistance.
37pub mod drand;
38/// Unified error taxonomy: [`KineticError`](error::KineticError), [`ResolutionError`](error::ResolutionError), [`PublishError`](error::PublishError), and [`RegistrationError`](error::RegistrationError).
39pub mod error;
40/// Protocol governance: council proposals, voting, and parameter updates.
41pub mod governance;
42
43/// Network security utilities for SSRF prevention.
44pub mod net;
45/// Idempotency key helpers for deduplicating daemon API requests.
46#[cfg(not(target_arch = "wasm32"))]
47pub mod request_id;
48/// Cross-platform graceful shutdown signal listener.
49pub mod shutdown;
50/// Core trait definitions: [`StorageEngine`](traits::StorageEngine) and [`VdfEngine`](traits::VdfEngine).
51pub mod traits;
52/// Shared wire-format types for P2P messages, DNS zones, and name records.
53pub mod types;
54#[cfg(not(target_arch = "wasm32"))]
55/// HTTP API error response wrapper ([`ApiError`](api_error::ApiError)) for Axum web handlers.
56#[cfg(not(target_arch = "wasm32"))]
57pub use api_error::ApiError;
58
59/// Primary protocol error taxonomy re-exported at crate root:
60/// - [`KineticError`]: Top-level unified error enum.
61/// - [`PublishError`]: Record publication failures (`KIN-PUB-*`).
62/// - [`RegistrationError`]: Name registration failures (`KIN-REG-*`).
63/// - [`ResolutionError`]: DHT name resolution failures (`KIN-RES-*`).
64/// - [`RecordRejectReason`]: Storage engine rejection codes.
65/// - [`VdfRejectReason`]: VDF proof validation rejection reasons.
66/// - [`Severity`]: Logging & monitoring alert severity classifier (`Info`, `Warning`, `Error`, `Critical`).
67pub use error::{
68 KineticError, PublishError, RecordRejectReason, RegistrationError, ResolutionError, Severity,
69 VdfRejectReason,
70};