Skip to main content

Crate drandite

Crate drandite 

Source
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.

  • 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:

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 Scheme is made of.
error
Types related to error handling.
scheme
The drand signature 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.
BeaconClient
A borrowed v2 client handle addressing a beacon by identifier.
ChainClient
A borrowed client handle addressing one chain by hash.
ChainHash
The canonical hash of a chain’s info.
ChainInfo
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.
GenesisSeed
The seed that chained schemes sign at round 1 in place of a previous signature.
HttpResponse
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.
UnixTimestamp
Seconds since the UNIX epoch. May be negative.
V1
Selects the v1 relay API for Client.
V2
Selects the v2 relay API for Client.
VerifiedAnyBeacon
The result of verifying a beacon with an AnyVerifier.
VerifiedBeacon
A beacon whose signature has been checked against a chain’s public key.
Verifier
Verifies the beacons of one chain.

Enums§

Error
An error from parsing, validating, or verifying.
SchemeId
The schemes this crate can verify.

Traits§

ApiVersion
Selects a relay API version.
HttpAdapter
A blocking transport for relay requests.
Scheme
A drand signature scheme.

Type Aliases§

Result
A specialized Result type for this crate.