Expand description
Drand beacon verification, relay clients, and timelock encryption.
The core API is always available at the crate root and through 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.
stdenables standard-library support in the selected components.wireenables transport-independent JSON models and request types.v1andv2enable their wire models, routes, and relay builders.httpenables wire conversions tohttp::Requestand impliesstd.clientenables the blocking client and both wire API versions. Without areqwest-*feature, provide an implementation ofclient::HttpAdapter.tlockenables fixed-size timelock encryption for unchained schemes.reqwest-rustls(default) andreqwest-native-tlsselect TLS backends for the client. They implyclientandstdand re-exportreqwest.reqwest-http3forwards reqwest’s experimental HTTP/3 support. It also requiresRUSTFLAGS="--cfg reqwest_unstable"; the client remains blocking.portable-blstselects 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:
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());§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.
Re-exports§
pub use drandite_core as core;pub use drandite_wire as wire;pub use drandite_client as client;pub use drandite_tlock as tlock;pub use reqwest;
Modules§
- any
- Runtime scheme dispatch.
- crypto
- The cryptographic building blocks a
Schemeis made of. - error
- Types related to error handling.
- scheme
- The
drandsignature schemes, as types. - types
- Round, schedule, and fixed-size byte values.
Structs§
- AnyVerifier
- A verifier whose scheme is chosen at runtime.
- Beacon
- A beacon as received from a relay. It has not been verified.
- Beacon
Client - A borrowed v2 client handle addressing a beacon by identifier.
- Chain
Client - A borrowed client handle addressing one chain by hash.
- Chain
Hash - The canonical hash of a chain’s info.
- Chain
Info - Everything a client needs to verify a chain’s beacons.
- Ciphertext
- An encrypted message bound to a drand chain and round.
- Client
- A blocking relay client with a selected API version and HTTP transport.
- Genesis
Seed - The seed that chained schemes sign at round 1 in place of a previous signature.
- Http
Response - An HTTP status and a fully buffered response body.
- Period
- The time between two rounds: a nonzero whole number of seconds.
- Randomness
- A round’s public randomness,
sha256(signature). - Round
- A beacon round.
- Timeline
- When rounds happen: round 1 at genesis, then one every period.
- Timelock
- Encrypts and decrypts messages for one drand chain.
- Unix
Timestamp - Seconds since the
UNIXepoch. May be negative. - V1
- Selects the v1 relay API for
Client. - V2
- Selects the v2 relay API for
Client. - Verified
AnyBeacon - The result of verifying a beacon with an
AnyVerifier. - Verified
Beacon - A beacon whose signature has been checked against a chain’s public key.
- Verifier
- Verifies the beacons of one chain.
Enums§
Traits§
- ApiVersion
- Selects a relay API version.
- Http
Adapter - A blocking transport for relay requests.
- Scheme
- A
drandsignature scheme.