beginner · ~10 min · hands-on

Your first request, end to end

By the time you finish this page, you'll have called the DICE devnet and printed a real 32-byte random value in your terminal.

STEP 01

install

STEP 02

configure

STEP 03

request

STEP 04

verify

#01 · Install the SDK

The SDK is published on npm. If you're starting fresh, run these two commands in a new directory:

Shell

mkdir my-dice-app && cd my-dice-app
npm init -y
npm install @dicelabs/vrf @solana/web3.js bs58

#02 · Configure a devnet wallet

DICE is live on Solana devnet. You need a funded wallet — the devnet faucet drops SOL for free. Save this as config.ts:

TypeScript

import { Keypair, Connection } from "@solana/web3.js";
import fs from "node:fs";

// Generate a keypair on first run, reuse on subsequent runs
const KEYFILE = ".my-wallet.json";
export const wallet = fs.existsSync(KEYFILE)
  ? Keypair.fromSecretKey(Uint8Array.from(JSON.parse(fs.readFileSync(KEYFILE, "utf8"))))
  : (() => {
      const kp = Keypair.generate();
      fs.writeFileSync(KEYFILE, JSON.stringify(Array.from(kp.secretKey)));
      return kp;
    })();

export const connection = new Connection("https://api.devnet.solana.com");

console.log("wallet:", wallet.publicKey.toBase58());

ℹ Note

After running it once, visit faucet.solana.com and airdrop 1 SOL to the address printed above.

#03 · Request one random value

Save as request.ts and run with npx tsx request.ts:

TypeScript

import { DiceClient } from "@dicelabs/vrf";
import { wallet, connection } from "./config.js";

const client = new DiceClient({ connection, cluster: "devnet" });

// Ask for one 32-byte random value. Blocks until the mesh responds
// (usually ~4 seconds).
const round = await client.requestRandomness({ payer: wallet });

console.log("round_id    :", round.id);
console.log("randomness  :", round.value.toString("hex"));
console.log("latency     :", round.latencyMs, "ms");
console.log("nodes       :", round.nodes.length, "/ 6");
console.log("tx          :", round.signature);

What you should see

round_id    : 0x4f3a9c1e...
randomness  : d1f7e2b4c9...8a3f (32 bytes / 64 hex chars)
latency     : 3842 ms
nodes       : 6 / 6
tx          : 3xS2y...qK7fQpN8YV3r (on-chain signature)

Copy the tx signature from your output and paste it into Solana Explorer. You'll see a transaction calling finalize_round on the DICE program, with the 32-byte randomness value embedded in the instruction data.

✓ Tip

That's it. You just asked six hardware devices for an unbiased random value, got it back in 4 seconds, and can prove it came from the real DICE mesh. Your dApp is one CPI away from doing this too.

#Where to go next