drandite 0.1.0

Drand beacon verification, relay clients, and timelock encryption
Documentation
//! Drand beacon verification, relay clients, and timelock encryption.
//!
//! The core API is always available at the crate root and through [`mod@core`].
//! It validates chain information, computes round schedules, and verifies beacon
//! signatures without performing I/O. Optional `wire`, `client`, and `tlock`
//! modules expose the corresponding component crates without wrapping their types.
//!
//! # Features
//!
//! Default features provide both relay API versions, a blocking Rustls client,
//! and timelock encryption. Disable default features for a core-only `no_std`
//! build; a global allocator is still required by chain information and `blst`.
//!
//! * `std` enables standard-library support in the selected components.
//! * `wire` enables transport-independent JSON models and request types.
//! * `v1` and `v2` enable their wire models, routes, and relay builders.
//! * `http` enables wire conversions to `http::Request` and implies `std`.
//! * `client` enables the blocking client and both wire API versions. Without a
//!   `reqwest-*` feature, provide an implementation of `client::HttpAdapter`.
//! * `tlock` enables fixed-size timelock encryption for unchained schemes.
//! * `reqwest-rustls` (default) and `reqwest-native-tls` select TLS backends for
//!   the client. They imply `client` and `std` and re-export `reqwest`.
//! * `reqwest-http3` forwards reqwest's experimental HTTP/3 support. It also
//!   requires `RUSTFLAGS="--cfg reqwest_unstable"`; the client remains blocking.
//! * `portable-blst` selects the portable BLS backend in every enabled component
//!   without enabling optional components.
//!
//! # Round schedules
//!
//! Round 1 starts at genesis; the instant before genesis has no current round.
//!
//! ```
//! use drandite::{Period, Round, Timeline, UnixTimestamp};
//!
//! let schedule = Timeline::new(
//!     UnixTimestamp::from_secs(1_700_000_000),
//!     Period::from_secs(3).unwrap(),
//! );
//! assert_eq!(schedule.checked_round_at(UnixTimestamp::from_secs(1_699_999_999)), None);
//! assert_eq!(schedule.round_at(UnixTimestamp::from_secs(1_700_000_003)).get(), 2);
//! assert_eq!(schedule.time_of(Round::FIRST).as_secs(), 1_700_000_000);
//! ```
//!
//! # Fetching and verifying a beacon
//!
//! With the default features, construct a transport and pin Quicknet's chain
//! hash independently of the relay:
//!
//! ```no_run
//! # #[cfg(feature = "reqwest-rustls")]
//! # {
//! use hex_literal::hex;
//! use drandite::{ChainHash, Client, V2, Verifier, reqwest, scheme::BlsUnchainedG1Rfc9380};
//! use std::time::Duration;
//!
//! let adapter = reqwest::blocking::Client::builder()
//!     .timeout(Duration::from_secs(10))
//!     .build()?;
//!
//! let client = Client::<V2, _>::new("https://api.drand.sh", adapter)?;
//!
//! let pinned = ChainHash::new(hex!("52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971"));
//! let chain = client.chain::<BlsUnchainedG1Rfc9380>(pinned);
//!
//! let info = chain.info()?;
//! let verified = Verifier::new(&info).verify(chain.latest()?)?;
//!
//! println!("{:?}", verified.randomness());
//! # }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! # Security
//!
//! HTTP success, JSON parsing, and canonicalization do not verify signatures.
//! Use an independently pinned chain hash and select the intended scheme before
//! verifying a beacon. Verification does not establish freshness; check the
//! returned round when requesting a specific round. Beacon randomness is public,
//! not a secret key or an encryption RNG seed.
//!
//! Timelock encryption requires an unchained scheme and a 16–32-byte message.
//! Encrypt a randomly generated symmetric key for larger payloads. Anyone with
//! the target signature can decrypt; signing-key holders can release it early.
//! See the `tlock` module for encoding and plaintext-erasure requirements.

#![cfg_attr(not(feature = "std"), no_std)]
#![warn(missing_docs)]

/// The complete verification and scheduling component.
pub use drandite_core as core;

pub use drandite_core::any::{AnyVerifier, SchemeId, VerifiedAnyBeacon};
pub use drandite_core::types::{ChainHash, GenesisSeed, Period, Randomness, Round, UnixTimestamp};
pub use drandite_core::*;

/// Transport-independent relay JSON models, routes, and requests.
#[cfg(feature = "wire")]
pub use drandite_wire as wire;

/// Blocking relay clients and the custom HTTP transport interface.
#[cfg(feature = "client")]
pub use drandite_client as client;

#[cfg(feature = "client")]
pub use drandite_client::{
    ApiVersion, BeaconClient, ChainClient, Client, HttpAdapter, HttpResponse, V1, V2,
};

/// Timelock encryption and its low-level cryptographic primitives.
#[cfg(feature = "tlock")]
pub use drandite_tlock as tlock;

#[cfg(feature = "tlock")]
pub use drandite_tlock::{Ciphertext, Timelock};

/// The HTTP transport used by the selected `reqwest-*` features.
#[cfg(any(
    feature = "reqwest-rustls",
    feature = "reqwest-native-tls",
    feature = "reqwest-http3"
))]
pub use reqwest;