Skip to main content
This guide walks you through building a verifiable random function (VRF) system using Compose and drand, a distributed randomness beacon. The system listens for on-chain randomness requests and fulfills them with cryptographically verifiable random values.

​
How it works

  1. Source contract emits a RandomnessRequested event
  2. Compose task is triggered by the on-chain event
  3. drand API provides verifiable randomness with BLS signatures
  4. Target contract receives the randomness with full proof data

​
Prerequisites

​
Project structure

VRF/
├── compose.yaml                    # Compose configuration
├── contracts/
│   └── RandomnessConsumer.sol      # Example contract
├── src/
│   ├── contracts/
│   │   └── RandomnessConsumer.json # Contract ABI (for codegen)
│   ├── lib/
│   │   └── drand.ts                # drand API utilities
│   └── tasks/
│       ├── generate-wallet.ts      # Wallet generation utility
│       ├── request-randomness.ts   # HTTP endpoint for requests
│       └── fulfill-randomness.ts   # Main fulfillment task

​
Step 1: Set up the project

Clone the example repository: 
git clone https://github.com/goldsky-io/documentation-examples.git
cd documentation-examples/compose/VRF

​
Step 2: Generate contract types

The project includes a RandomnessConsumer.json ABI in src/contracts/. Generate the typed contract class: 
goldsky compose codegen
This creates a typed RandomnessConsumer class that provides type-safe contract interaction instead of raw function signature strings.

​
Step 3: Generate your Compose wallet

Start Compose locally in one terminal: 
goldsky compose start --fork-chains
--fork-chains allows you to run a smart wallet locally. You can also use a private key wallet for your local Compose app. See more here. In another terminal, get your wallet address: 
goldsky compose callTask generate_wallet '{}'
Save the wallet address — this will be the authorized fulfiller for your contract.

​
Step 4: Deploy the smart contract

The RandomnessConsumer.sol contract handles randomness requests and fulfillment: 
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract RandomnessConsumer {
    struct RandomnessRequest {
        address requester;
        bool fulfilled;
        bytes32 randomness;
        uint64 round;
        bytes signature;
    }

    address public fulfiller;
    uint256 public nextRequestId;
    mapping(uint256 => RandomnessRequest) public requests;

    event RandomnessRequested(uint256 indexed requestId, address indexed requester);
    event RandomnessFulfilled(uint256 indexed requestId, bytes32 randomness, uint64 round, bytes signature);

    constructor(address _fulfiller) {
        fulfiller = _fulfiller;
    }

    function requestRandomness() external returns (uint256 requestId) {
        requestId = nextRequestId++;
        requests[requestId] = RandomnessRequest({
            requester: msg.sender,
            fulfilled: false,
            randomness: bytes32(0),
            round: 0,
            signature: ""
        });
        emit RandomnessRequested(requestId, msg.sender);
    }

    function fulfillRandomness(
        uint256 requestId,
        bytes32 randomness,
        uint64 round,
        bytes calldata signature
    ) external {
        require(msg.sender == fulfiller, "OnlyFulfiller");
        RandomnessRequest storage request = requests[requestId];
        require(request.requester != address(0), "RequestNotFound");
        require(!request.fulfilled, "AlreadyFulfilled");

        request.fulfilled = true;
        request.randomness = randomness;
        request.round = round;
        request.signature = signature;

        emit RandomnessFulfilled(requestId, randomness, round, signature);
    }
}
Deploy to Base Sepolia: 
forge create contracts/RandomnessConsumer.sol:RandomnessConsumer \
  --rpc-url https://sepolia.base.org \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --constructor-args 0xYOUR_COMPOSE_WALLET_ADDRESS
Save the deployed contract address.

​
Step 5: Configure the Compose app

Update compose.yaml with your contract address: 
name: "compose-vrf"
api_version: "stable"

tasks:
  - path: "./src/tasks/generate-wallet.ts"
    name: "generate_wallet"
    triggers:
      - type: "http"
        authentication: "auth_token"

  - path: "./src/tasks/request-randomness.ts"
    name: "request_randomness"
    triggers:
      - type: "http"
        authentication: "auth_token"

  - path: "./src/tasks/fulfill-randomness.ts"
    name: "fulfill_randomness"
    triggers:
      - type: "onchain_event"
        network: "base_sepolia"
        contract: "0xYOUR_DEPLOYED_CONTRACT_ADDRESS"
        events:
          - "RandomnessRequested(uint256,address)"
    retry_config:
      max_attempts: 3
      initial_interval_ms: 1000
      backoff_factor: 2
Update the contract address in the task files:
  • src/tasks/fulfill-randomness.ts — TARGET_CONTRACT
  • src/tasks/request-randomness.ts — CONTRACT_ADDRESS

​
Step 6: Understand the fulfillment task

The fulfill-randomness.ts task handles the core logic: 
import { TaskContext, OnchainEvent } from "compose";
import {
  fetchLatestRandomness,
  toBytes32,
  toBytes,
  DRAND_CHAIN_INFO,
} from "../lib/drand.ts";

const CONTRACT_ADDRESS = "0xYOUR_DEPLOYED_CONTRACT_ADDRESS";

export async function main(context: TaskContext, event?: OnchainEvent) {
  const { fetch, evm, logEvent } = context;

  // Extract request ID from the event
  const requestId = event?.topics[1] ? BigInt(event.topics[1]) : 0n;

  // Fetch randomness from drand
  const drandResponse = await fetchLatestRandomness(fetch);

  await logEvent({
    code: "DRAND_FETCHED",
    message: `Fetched drand round ${drandResponse.round}`,
    data: JSON.stringify({ round: drandResponse.round }),
  });

  // Get wallet and instantiate typed contract (generated from src/contracts/RandomnessConsumer.json)
  const wallet = await evm.wallet({
    name: "randomness-fulfiller",
  });

  const contract = new evm.contracts.RandomnessConsumer(
    CONTRACT_ADDRESS,
    evm.chains.baseSepolia,
    wallet
  );

  // Fulfill the randomness request on-chain
  const { hash } = await contract.fulfillRandomness(
    requestId.toString(),
    toBytes32(drandResponse.randomness),
    drandResponse.round,
    toBytes(drandResponse.signature)
  );

  await logEvent({
    code: "RANDOMNESS_FULFILLED",
    message: `Fulfilled request ${requestId} in tx ${hash}`,
    data: JSON.stringify({
      requestId: requestId.toString(),
      txHash: hash,
    }),
  });

  return {
    success: true,
    requestId: requestId.toString(),
    transactionHash: hash,
    drand: {
      round: String(drandResponse.round),
      randomness: toBytes32(drandResponse.randomness),
      chainHash: DRAND_CHAIN_INFO.hash,
    },
  };
}
Key points:
  • Contract codegen — evm.contracts.RandomnessConsumer is generated from the ABI JSON, providing type-safe method calls like contract.fulfillRandomness(...) instead of raw function signature strings
  • Uses evm.chains.baseSepolia — a built-in chain, no custom configuration needed
  • Gas is sponsored by default on supported chains

​
Step 7: Understand the drand integration

The drand.ts library fetches verifiable randomness: 
export type DrandResponse = {
  round: number;
  randomness: string; // hex - sha256(signature)
  signature: string;  // hex - BLS12-381 signature (96 bytes)
  previous_signature: string;
};

export const DRAND_CHAIN_INFO = {
  hash: "52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971",
  publicKey: "83cf0f2896adee7eb8b5f01fcad3912212c437e0073e911fb90022d3e760183c8c4b450b6a0a6c3ac6a5776a2d1064510d1fec758c921cc22b0e17e63aaf4bcb5ed66304de9cf809bd274ca73bab4af5a6e9c76a4bc09e76eae8991ef5ece45a",
  genesisTime: 1692803367,
  period: 3, // seconds between rounds
};

export async function fetchLatestRandomness(
  fetchFn: <T>(url: string) => Promise<T | undefined>
): Promise<DrandResponse> {
  const response = await fetchFn<DrandResponse>(
    `https://api.drand.sh/${DRAND_CHAIN_INFO.hash}/public/latest`
  );
  if (!response) {
    throw new Error("Failed to fetch randomness from drand");
  }
  return response;
}
The randomness is verifiable using drand’s BLS12-381 signatures. Anyone can verify the randomness by checking that sha256(signature) == randomness using the public key.

​
Step 8: Run locally

Start the Compose app: 
goldsky compose start --fork-chains

​
Step 9: Test the system

Request randomness by calling the contract: 
cast send 0xYOUR_CONTRACT_ADDRESS "requestRandomness()" \
  --rpc-url https://sepolia.base.org \
  --private-key $PRIVATE_KEY
Watch the Compose logs. You should see:
  1. The RandomnessRequested event being detected
  2. Randomness fetched from drand
  3. The fulfillment transaction submitted

​
Step 10: Deploy to Goldsky

Once tested locally, deploy to Goldsky’s cloud: 
goldsky compose deploy

​
Customization

​
Different chains

Use any supported chain — no custom configuration needed: 
const wallet = await evm.wallet({ name: "my-wallet" });
const result = await wallet.writeContract(
  evm.chains.arbitrumSepolia,  // or baseSepolia, polygonAmoy, etc.
  CONTRACT_ADDRESS,
  "myFunction(uint256)",
  [arg1]
);

​
Different events

Modify the compose.yaml to listen for different events: 
triggers:
  - type: "onchain_event"
    network: "base_sepolia"
    contract: "0xYOUR_CONTRACT"
    events:
      - "YourCustomEvent(uint256,address,bytes32)"

​
Resources