Drand docs
Look up any call, event, or storage item with code examples. Runtime v490 · Block #9,478,217
Developer documentation for the Drand pallet of the Subtensor blockchain, part of the Bittensor decentralized AI network. This page is designed for developers integrating with the chain: look up any call, event, or storage item, copy code examples in TypeScript, Python, or Rust, and filter by your role. For in-depth explanations, version history, and relationships between items, see the Reference section.
Drand
Verify and write a pulse from the beacon into the runtime
Calls 3
Submits and verifies a Drand randomness pulse to be stored on-chain.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
pulses_payload | PulsesPayload | — | pulses_payload (PulsesPayload) |
signature | Option | — | signature (Option) |
// ----------------------------------------------------------------------
// HEADS UP: 1 arg below has a complex type with no usable default.
// Look for `undefined as any` and replace it with real value
// before running — the snippet compiles, but will fail at runtime as-is.
// ----------------------------------------------------------------------
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Build write_pulse call (typed, named args)
const pulses_payload = undefined as any /* PulsesPayload — replace with real value */;
const signature = undefined;
const tx = api.tx.Drand.write_pulse({
pulses_payload,
signature,
});Updates the Drand beacon configuration used for pulse verification.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
config_payload | BeaconConfigurationPayload | — | config_payload (BeaconConfigurationPayload) |
signature | Option | — | signature (Option) |
// ----------------------------------------------------------------------
// HEADS UP: 1 arg below has a complex type with no usable default.
// Look for `undefined as any` and replace it with real value
// before running — the snippet compiles, but will fail at runtime as-is.
// ----------------------------------------------------------------------
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Build set_beacon_config call (typed, named args)
const config_payload = undefined as any /* BeaconConfigurationPayload — replace with real value */;
const signature = undefined;
const tx = api.tx.Drand.set_beacon_config({
config_payload,
signature,
});Sets the oldest round number that the chain will retain in storage.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
oldest_round | u64 | Integer | oldest_round (u64) |
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Build set_oldest_stored_round call (typed, named args)
const oldest_round = 0n;
const tx = api.tx.Drand.set_oldest_stored_round({
oldest_round,
});Events 3
Emitted when the Drand beacon configuration has been updated.
When it fires
- Caller has root/sudo privileges
- New configuration is valid
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Subscribe to BeaconConfigChanged events
client.finalizedBlock$.subscribe(async (block) => {
const events = await api.event.Drand.BeaconConfigChanged.get(block.hash);
for (const evt of events) {
console.log("BeaconConfigChanged:", evt.payload);
}
});Emitted when a new randomness pulse has been successfully verified and stored.
When it fires
- Pulse signature is valid against beacon configuration
- Round number is valid (typically sequential or within bounds)
- Pulse has not already been recorded
Fields
| Name | Type | Format | Description |
|---|---|---|---|
rounds | Vec<u64> | Array of Integer | Drand round numbers for the new randomness pulses |
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Subscribe to NewPulse events
client.finalizedBlock$.subscribe(async (block) => {
const events = await api.event.Drand.NewPulse.get(block.hash);
for (const evt of events) {
console.log("NewPulse:", evt.payload);
}
});Emitted when the oldest stored round boundary has been updated.
When it fires
- Caller has root/sudo privileges
- New oldest round is valid
Fields
| Name | Type | Format | Description |
|---|---|---|---|
oldest_round | u64 | Integer | New oldest stored round number boundary |
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Subscribe to SetOldestStoredRound events
client.finalizedBlock$.subscribe(async (block) => {
const events = await api.event.Drand.SetOldestStoredRound.get(block.hash);
for (const evt of events) {
console.log("SetOldestStoredRound:", evt.payload);
}
});Storage 6
The Drand beacon configuration used for verifying randomness pulses.
BeaconConfiguration import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Query BeaconConfig storage (no keys - plain value)
const result = await api.query.Drand.BeaconConfig.getValue();
console.log("BeaconConfig:", result);Tracks whether specific migrations have been executed.
bool (Boolean (true/false))Keys
| Name | Type | Format | Description |
|---|---|---|---|
key1 | BoundedVec | — | — |
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Query HasMigrationRun storage
const key1 = new Uint8Array(0);
const result = await api.query.Drand.HasMigrationRun.getValue(key1);
console.log("HasMigrationRun:", result);The most recent Drand round number stored on-chain.
u64 (Integer)import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Query LastStoredRound storage (no keys - plain value)
const result = await api.query.Drand.LastStoredRound.getValue();
console.log("LastStoredRound:", result);The block number when the next unsigned pulse transaction will be accepted.
u32 (Integer)import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Query NextUnsignedAt storage (no keys - plain value)
const result = await api.query.Drand.NextUnsignedAt.getValue();
console.log("NextUnsignedAt:", result);The oldest Drand round number retained in storage.
u64 (Integer)import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Query OldestStoredRound storage (no keys - plain value)
const result = await api.query.Drand.OldestStoredRound.getValue();
console.log("OldestStoredRound:", result);Verified randomness pulses from the Drand beacon, keyed by round number.
Pulse Keys
| Name | Type | Format | Description |
|---|---|---|---|
key1 | u64 | Integer | — |
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Query Pulses storage
const key1 = 0n;
const result = await api.query.Drand.Pulses.getValue(key1);
console.log("Pulses:", result);Constants 2
Maximum milliseconds to wait for HTTP requests to the Drand beacon.
u64"1000"import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Query HttpFetchTimeout constant
const value = await api.constants.Drand.HttpFetchTimeout();
console.log("HttpFetchTimeout:", value);
// Balance: divide by 10^9 for TAO
const tao = value / 1_000_000_000n;Base priority for unsigned Drand pulse transactions in the transaction pool.
u64"1048576"import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Query UnsignedPriority constant
const value = await api.constants.Drand.UnsignedPriority();
console.log("UnsignedPriority:", value);
// Balance: divide by 10^9 for TAO
const tao = value / 1_000_000_000n;Errors 6
A required value was not found in storage when expected.
Common Causes
- Trying to access storage that hasn't been initialized
- Querying a round that doesn't exist in Pulses storage
- BeaconConfig not yet set after chain genesis
How to Fix
Check if BeaconConfig has been initialized via set_beacon_config,Verify the round number exists - query LastStoredRound and OldestStoredRound for valid range,Ensure all required storage is initialized before operations
An internal counter would exceed its maximum value (u32::MAX).
Common Causes
- Extremely long-running chain without storage cleanup
- Bug in increment logic (should be rare)
How to Fix
This is an internal runtime error - report to chain developers,May require runtime upgrade to fix counter handling
The offchain worker failed to connect to the Drand beacon API.
Common Causes
- Network connectivity issues to Drand endpoints
- Drand beacon API is down or unreachable
- Firewall or DNS issues blocking outbound HTTP
- HTTP timeout exceeded (check HttpFetchTimeout constant)
How to Fix
Check network connectivity from the validator node,Verify Drand endpoints are accessible: curl https://api.drand.sh/public/latest,Check if firewall rules allow outbound HTTPS,Consider running a local Drand relay for better reliability
The submitted Drand pulse failed cryptographic verification.
Common Causes
- Pulse signature doesn't match the beacon configuration
- Corrupted pulse data during transmission
- Wrong beacon configuration (key mismatch)
- Submitting a pulse from a different Drand network
How to Fix
Verify the pulse was fetched from the correct Drand beacon,Check BeaconConfig matches your source (public key, chain hash),Ensure pulse data wasn't modified between fetch and submission,Confirm the Drand network hasn't migrated to new keys
The pulse round number is invalid or out of expected sequence.
Common Causes
- Submitting an old round that's already been recorded
- Round number is before OldestStoredRound
- Round number jumps unexpectedly (missing intermediate rounds)
How to Fix
Query LastStoredRound to see what's already submitted,Check OldestStoredRound for the valid range floor,Ensure offchain worker fetches the latest, not cached, rounds
An error occurred during the pulse verification process.
Common Causes
- Malformed pulse data (wrong encoding or structure)
- BLS signature verification library error
- Corrupt beacon configuration
How to Fix
Check pulse data encoding matches expected format,Verify BeaconConfig is properly initialized,Check for runtime version compatibility issues