drand-client

library1.4.2jsnpmunverified

A JavaScript/TypeScript client library for the League of Entropy's drand distributed randomness beacon network. Currently at v1.4.2, it provides cryptographic verification of randomness using BLS signatures (BLS12-381). Key differentiators include support for HTTP/WebSocket transports, multi-node fastest-client selection, and optional beacon caching. Ships TypeScript types. Supports modern browsers, Node.js >=10.4, and Deno via CDN. Compared to alternatives like randgen or wolfram, drand-client leverages a decentralized network of independent nodes for publicly verifiable, unbiased randomness.

security

npm install drand-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DRAND-CLIENT

drand-client

securityjavascriptv1.4.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fetchBeacon

✓ import { fetchBeacon } from 'drand-client'

✗ const fetchBeacon = require('drand-client').fetchBeacon

ESM-only module; require() will not work in Node.js ESM mode unless using dynamic import. TypeScript should already have 'esModuleInterop' set.

HttpChainClient

✓ import { HttpChainClient } from 'drand-client'

✗ import HttpChainClient from 'drand-client'

Named export, not default. Common mistake when treating it as a default export.

FastestNodeClient

✓ import { FastestNodeClient } from 'drand-client'

✗ const { FastestNodeClient } = require('drand-client'); // only works with dynamic import()

Must be imported via ESM import statement. CJS require is not supported. In Node.js, use dynamic import: const { FastestNodeClient } = await import('drand-client').

chainHash

✓ import { chainHash } from 'drand-client'

Used for chain verification. This is a constant matching the League of Entropy's default chain hash.

This shows how to create a drand client, fetch the latest beacon, and access its randomness and round number.

import { fetchBeacon, HttpChainClient, HttpCachingChain, chainHash, publicKey } from 'drand-client'; const chain = new HttpCachingChain('https://api.drand.sh', { disableBeaconVerification: false, noCache: false, chainVerificationParams: { chainHash, publicKey } }); const client = new HttpChainClient(chain, { chainVerificationParams: { chainHash, publicKey } }); async function getLatestRandomness() { const beacon = await fetchBeacon(client); console.log('Randomness:', beacon.randomness); console.log('Round:', beacon.round); } getLatestRandomness().catch(console.error);

Debug

Known issues

breakingIn v1.3.0+, the `chainHash` and `publicKey` module-level constants were changed to match the 'quicknet' chain. If your code expects the old 'mainnet' values, you must explicitly specify them.

fix

Import and use the correct chain hash and public key constants from the library, or provide them explicitly via options.

affects: >=1.3.0

breakingFrom v1.2.0 onward, `fetchBeacon` and `fetchBeaconByTime` now return a Promise resolving to a `Beacon` object with renamed fields: `randomness` (previously `round` was also on the root, now nested). Check your code using these functions.

fix

Update property access: `beacon.randomness` for the random value, `beacon.round` for the round number.

affects: >=1.2.0

deprecatedThe `HttpCachingChain` constructor's `options` parameter no longer accepts `chainVerificationParams` directly. Instead, pass them via the overarching client options.

fix

Move `chainVerificationParams` to the options passed to the client (e.g., `HttpChainClient`), not the chain.

affects: >=1.1.0

gotchaWhen using a multi-node setup with `FastestNodeClient`, you must call `fastestNodeClient.start()` to begin periodic checks; otherwise, it will not automatically select the fastest node. Common mistake leading to degraded performance.

fix

Always call `.start()` after constructing `FastestNodeClient`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: drand_client_1.fetchBeacon is not a function

CommonJS require is being used in an ESM-only package.

fix

Switch to ESM import: `import { fetchBeacon } from 'drand-client'` or use dynamic import: `const { fetchBeacon } = await import('drand-client')`

Error: Chain verification failed: chain hash mismatch

The `chainVerificationParams` provided do not match the chain endpoint's actual parameters.

fix

Double-check the chain hash and public key. Use the exported constants `chainHash` and `publicKey` or obtain them from the drand chain's `/info` endpoint.

SyntaxError: Unexpected token 'export'

The JavaScript environment (e.g., older Node or browser) does not support ES modules.

fix

Use a bundler that transpiles ESM to CommonJS, or use the CDN version which is pre-bundled.

Upgrade

Version history

1.4.2latest on npm

Audit

Dependencies

isomorphic-fetchoptionalPolyfill for Fetch API in older Node.js versions (Node <18). Not needed in modern environments or Deno/browser.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/drand/drand-client ↗

packagedrand-client ↗

homepagehttps://github.com/drand/drand-client#readme ↗