Drand

Garaga provides maintained contracts for the drand distributed randomness beacon. These enable:

• On-chain signature verification of drand rounds for verifiable randomness

• Time-lock encryption (tlock): encrypt data that can only be decrypted after a specific drand round is published

What is drand?

drand is a distributed randomness beacon that provides:

• Unpredictable randomness: Values cannot be known before generation

• Unbiasable output: No single party can influence results

• Public verifiability: Anyone can verify the randomness is legitimate

• Regular intervals: New randomness every 3 seconds (quicknet)

What is tlock?

Time-lock encryption (tlock) leverages drand's BLS threshold signatures to create an identity-based encryption (IBE) scheme where the "identity" is a future drand round number. A message encrypted for round N can only be decrypted once drand publishes the signature for round N. No single party can decrypt early.

Use Cases

Application	How tlock helps
Sealed-bid auctions	Bids encrypted until auction close (a specific drand round)
Scheduled reveals	Information released at a predetermined time
Fair launches	Token distributions with time-locked claiming
Commit-reveal schemes	Players commit encrypted moves, revealed together after a round

Contracts

Drand Quicknet Verifier

Verifies drand BLS signatures and stores them on-chain.

Network	Class Hash
Mainnet	0x86bf4360e082cd786bd785d3345df32777db89cd26b761f3e85b1993addfd0
Sepolia	0x86bf4360e082cd786bd785d3345df32777db89cd26b761f3e85b1993addfd0

#[starknet::interface]
trait IDrandQuicknet<TContractState> {
    /// Verify a drand round BLS signature and store it on-chain.
    fn verify_round(
        ref self: TContractState, full_proof_with_hints: Span<felt252>,
    ) -> Result<u64, felt252>;

    /// Look up the stored signature for a previously verified round.
    fn get_signature_for_round(
        self: @TContractState, round_number: u64,
    ) -> Result<G1Point, felt252>;

    /// Look up the randomness (poseidon_hash(signature)) for a previously verified round.
    fn get_randomness_for_round(
        self: @TContractState, round_number: u64,
    ) -> Result<felt252, felt252>;
}

Drand Decrypt Quicknet

Wraps the verifier to add on-chain tlock decryption. Deploy this contract yourself and point it at the verifier class hash.

#[starknet::interface]
trait IDrandDecryptQuicknet<TContractState> {
    /// Verify a drand round BLS signature via library_call to the verifier class.
    fn verify_round(
        ref self: TContractState, full_proof_with_hints: Span<felt252>,
    ) -> Result<u64, felt252>;

    /// Read the stored signature for a previously verified round.
    fn get_signature_for_round(
        self: @TContractState, round_number: u64,
    ) -> Result<G1Point, felt252>;

    /// Get poseidon_hash(signature) for a previously verified round.
    fn get_randomness_for_round(
        self: @TContractState, round_number: u64,
    ) -> Result<felt252, felt252>;

    /// Decrypt a tlock ciphertext for a given round.
    /// If the round signature is not yet stored, a DrandHint must follow in the calldata.
    fn decrypt_cipher_text(
        ref self: TContractState, full_proof_with_hints: Span<felt252>,
    ) -> Result<Span<u8>, felt252>;
}

The verifier contract is designed for library calls and does not need to be deployed. The decrypt contract wraps it and must be deployed since it stores signatures in its own storage.

Quicknet Configuration

Both contracts are configured for drand's quicknet network:

Parameter	Value
Chain Hash	52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971
Public Key	G2 point on BLS12-381 (hardcoded in contract)
Period	3 seconds
Genesis	1692803367 (Aug 23, 2023)

---

Verifiable Randomness

Fetching drand Randomness

First, fetch randomness from drand's HTTP API:

# Get the latest round
curl https://api.drand.sh/52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971/public/latest

# Get a specific round
curl https://api.drand.sh/52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971/public/12345

Response:

{
  "round": 12345,
  "randomness": "8b9c...",
  "signature": "a1b2..."
}

Generating Verification Calldata

Use the Garaga SDK to generate the full_proof_with_hints calldata from the drand response:

Python

from garaga.starknet.tests_and_calldata_generators.drand_calldata import (
    drand_round_to_calldata,
)

# Generate calldata for a specific round (fetches from drand API automatically)
calldata = drand_round_to_calldata(round_number=12345)
# Returns list[int] ready for on-chain verification

# Use the Rust backend for better performance
calldata = drand_round_to_calldata(round_number=12345, use_rust=True)

TypeScript

import * as garaga from 'garaga';

await garaga.init();

// Fetch drand randomness and build calldata
const drandData = await garaga.fetchDrandRandomness(12345);
const calldata = garaga.getDrandCallData(drandData);

On-Chain Verification with Library Call

Use library_call_syscall to call the drand verifier contract:

use starknet::{SyscallResultTrait, syscalls};
use garaga::definitions::G1Point;

const DRAND_QUICKNET_CLASS_HASH: felt252 =
    0x86bf4360e082cd786bd785d3345df32777db89cd26b761f3e85b1993addfd0;

fn verify_drand_round(full_proof_with_hints: Span<felt252>) -> u64 {
    let mut call_data: Array<felt252> = array![];
    Serde::serialize(@full_proof_with_hints, ref call_data);

    let mut result = syscalls::library_call_syscall(
        DRAND_QUICKNET_CLASS_HASH.try_into().unwrap(),
        selector!("verify_round"),
        call_data.span(),
    ).unwrap_syscall();

    let round: Result<u64, felt252> = Serde::deserialize(ref result).unwrap();
    round.unwrap()
}

---

Time-Lock Encryption (tlock)

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        ENCRYPTION (off-chain)                    │
│                                                                  │
│   1. Choose a future drand round number N                        │
│   2. Encrypt 16-byte message using drand's public key + round N  │
│   3. Produces CipherText { U: G2Point, V: [u8;16], W: [u8;16] } │
│   4. Store ciphertext on-chain or off-chain                      │
│                                                                  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                          time passes...
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│              drand publishes round N signature                   │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                       DECRYPTION (on-chain)                      │
│                                                                  │
│   1. Verify the drand signature for round N (BLS pairing check)  │
│   2. Use signature to decrypt: e(signature, U) recovers key      │
│   3. XOR-decrypt to recover the original 16-byte message         │
│   4. Verify ciphertext integrity (U = r·G₂ check)               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Message size: tlock encrypts a 16-byte (128-bit) message. For larger payloads, encrypt a symmetric key with tlock and use it to encrypt the larger data off-chain.

Encrypting a Message (Off-Chain)

Use the Garaga SDK to encrypt a message for a future drand round:

Python

from garaga.starknet.tests_and_calldata_generators.drand_calldata import (
    drand_encrypt_to_calldata,
)

# Encrypt a 16-byte message for a future round
message = b"secret message!!"  # exactly 16 bytes
round_number = 100000  # a future drand round

# Generate calldata containing the encrypted ciphertext
calldata = drand_encrypt_to_calldata(round_number, message)

# Use the Rust backend for better performance
calldata = drand_encrypt_to_calldata(round_number, message, use_rust=True)

TypeScript

import * as garaga from 'garaga';

await garaga.init();

// Prepare 16-byte message and randomness
const message = new Uint8Array(16);
message.set(new TextEncoder().encode('secret message!!'));

const randomness = crypto.getRandomValues(new Uint8Array(16));

// Encrypt for a specific future round
const calldata = garaga.encryptToDrandRoundAndGetCallData(
  100000,     // round number
  message,    // 16-byte message
  randomness, // 16-byte randomness
);

Rust

use garaga_rs::calldata::drand_tlock_calldata::drand_tlock_encrypt_calldata_builder;
use num_bigint::BigUint;

let round_number = 100000u64;
let message: [u8; 16] = *b"secret message!!";
let randomness: [u8; 16] = rand::random();

let values = vec![
    BigUint::from(round_number),
    BigUint::from_bytes_be(&message),
    BigUint::from_bytes_be(&randomness),
];

let calldata = drand_tlock_encrypt_calldata_builder(&values).unwrap();

Decrypting On-Chain

The decrypt_cipher_text function on the decrypt contract handles two scenarios:

1. Round already verified: If the drand signature for the round is already stored, only the ciphertext calldata is needed.

2. Round not yet verified: The ciphertext calldata is followed by the drand verification hint, and both verification and decryption happen in a single transaction.

Scenario 1: Verify first, then decrypt

from garaga.starknet.tests_and_calldata_generators.drand_calldata import (
    drand_round_to_calldata,
    drand_encrypt_to_calldata,
)

# Step 1: Verify the round (stores the signature)
verify_calldata = drand_round_to_calldata(round_number=12345)
# Call contract.verify_round(verify_calldata)

# Step 2: Decrypt (uses stored signature)
decrypt_calldata = drand_encrypt_to_calldata(12345, message)
# Call contract.decrypt_cipher_text(decrypt_calldata)

Scenario 2: Verify and decrypt in one transaction

# Combine encryption calldata + verification calldata
encrypt_cd = drand_encrypt_to_calldata(round_number, message)
verify_cd = drand_round_to_calldata(round_number)

# Strip the length prefix from each, combine, and add new length prefix.
# This works because decrypt_cipher_text deserializes the DrandDecryptHint
# (round + ciphertext) first, then passes the remaining bytes to verify_round.
combined_data = encrypt_cd[1:] + verify_cd[1:]
combined_calldata = [len(combined_data)] + combined_data
# Call contract.decrypt_cipher_text(combined_calldata)

Cairo: CipherText Struct

The tlock ciphertext is defined in garaga::apps::drand:

use garaga::apps::drand::CipherText;
use garaga::definitions::G2Point;

/// The result of a timelock encryption over drand quicknet.
struct CipherText {
    U: G2Point,   // r·G₂ — the ephemeral public key
    V: [u8; 16],  // sigma XOR H₂(r·e(H(round), pk))
    W: [u8; 16],  // message XOR H₄(sigma)
}

Cairo: Direct Decryption in Your Contract

If you want to call the decrypt_at_round function directly from the garaga library:

use garaga::apps::drand::{CipherText, decrypt_at_round};
use garaga::definitions::G1Point;

fn my_decrypt(signature: G1Point, ciphertext: CipherText) -> [u8; 16] {
    // Performs: miller loop, final exponentiation, XOR decryption, and U = r·G₂ check
    decrypt_at_round(signature, ciphertext)
}

decrypt_at_round verifies ciphertext integrity (U = r·G₂) but does not verify that the provided signature is a valid drand BLS signature. You must verify the signature separately via verify_round or perform your own pairing check before calling this function.

---

Example: On-Chain Lottery

#[starknet::contract]
mod Lottery {
    use starknet::ContractAddress;
    use starknet::storage::{
        Map, StorageMapReadAccess, StorageMapWriteAccess,
        StoragePointerReadAccess, StoragePointerWriteAccess,
    };
    use starknet::{SyscallResultTrait, syscalls};

    const DRAND_QUICKNET_CLASS_HASH: felt252 =
        0x86bf4360e082cd786bd785d3345df32777db89cd26b761f3e85b1993addfd0;

    #[storage]
    struct Storage {
        participants: Map<u32, ContractAddress>,
        participant_count: u32,
        target_round: u64,
        is_open: bool,
    }

    #[external(v0)]
    fn enter_lottery(ref self: ContractState) {
        assert!(self.is_open.read(), "Lottery closed");
        let count = self.participant_count.read();
        self.participants.write(count, starknet::get_caller_address());
        self.participant_count.write(count + 1);
    }

    #[external(v0)]
    fn draw_winner(
        ref self: ContractState,
        full_proof_with_hints: Span<felt252>,
    ) -> ContractAddress {
        let mut call_data: Array<felt252> = array![];
        Serde::serialize(@full_proof_with_hints, ref call_data);

        let mut result = syscalls::library_call_syscall(
            DRAND_QUICKNET_CLASS_HASH.try_into().unwrap(),
            selector!("verify_round"),
            call_data.span(),
        ).unwrap_syscall();

        let round_result: Result<u64, felt252> = Serde::deserialize(ref result).unwrap();
        let verified_round = round_result.unwrap();

        assert!(verified_round == self.target_round.read(), "Wrong round");

        let count: u256 = self.participant_count.read().into();
        // Retrieve randomness from the verified round
        let mut rand_call_data: Array<felt252> = array![];
        Serde::serialize(@verified_round, ref rand_call_data);

        let mut rand_result = syscalls::library_call_syscall(
            DRAND_QUICKNET_CLASS_HASH.try_into().unwrap(),
            selector!("get_randomness_for_round"),
            rand_call_data.span(),
        ).unwrap_syscall();

        let randomness: Result<felt252, felt252> = Serde::deserialize(ref rand_result).unwrap();
        let winner_index: u32 = (randomness.unwrap().into() % count).try_into().unwrap();

        self.participants.read(winner_index)
    }
}

Example: Sealed-Bid Auction with tlock

A sketch of how tlock enables sealed-bid auctions. Bids are encrypted for a future reveal round. Once drand publishes that round, bids can be decrypted on-chain.

1. Auction opens — bidders encrypt their bids for reveal_round using tlock
2. Bidders submit a hash of their ciphertext on-chain (commitment)
3. Auction closes — no more bids accepted
4. drand publishes reveal_round signature
5. Anyone calls decrypt_cipher_text to reveal each bid on-chain
6. Contract determines the winner from the decrypted bids

The ciphertext itself (a G2Point + 32 bytes) can be stored off-chain (e.g., IPFS) with only a commitment hash on-chain, or submitted directly in the decryption transaction.

Helper Functions

The garaga::apps::drand module provides utilities for working with drand rounds:

use garaga::apps::drand::{timestamp_to_round, round_to_timestamp};

// Convert a Unix timestamp to a drand round number
let round = timestamp_to_round(1692803370);  // returns 2

// Convert a drand round number to a Unix timestamp
let timestamp = round_to_timestamp(2);  // returns 1692803370

Security Considerations

• Round timing: Ensure you're using the correct round for your application's timing requirements. Use timestamp_to_round to map wall-clock time to drand rounds.

• Message size: tlock encrypts exactly 16 bytes. Use it to encrypt a symmetric key for larger payloads.

• Ciphertext integrity: The decrypt_at_round function verifies U = r·G₂ to ensure the ciphertext was formed correctly. Tampered ciphertexts will be rejected.

• Finality: Once a drand round is published, the signature is permanent. The ciphertext becomes decryptable by anyone with the round signature.

• Fallback: Consider implementing fallback mechanisms if drand becomes unavailable.

Resources

• drand Website

• drand API Documentation

• Quicknet Information

• tlock Paper — "tlock: Practical Timelock Encryption from Threshold BLS"

• Verifier Source Code

• Decrypt Contract Source Code