Skip to main content

Client-Side Randomness

Overview​

This guide introduces randomness-js, a JavaScript/TypeScript SDK designed to bring secure, on-chain randomness into your client-side applications. It acts as the bridge between your dApp's frontend or backend and the RandomnessSender smart contract, which is part of the randomness-solidity library. By using this SDK, your application can easily request and verify random numbers generated by the dcipher network, ensuring fairness and unpredictability in your projects.

Core Concepts​

Before diving into the functions, it's important to understand two core ideas:

Client-Chain Interaction​

The SDK does not generate randomness by itself. Instead, it creates and sends a transaction to the on-chain RandomnessSender contract. This contract then communicates with the dcipher network to produce the random value. This ensures the randomness is generated with the security of the underlying blockchain.

Request & Verify Flow​

The process involves two main actions:

  1. Your application requests a random number
  2. After the on-chain transaction is complete, your application should verify the result

This client-side verification step provides an extra layer of assurance that the randomness is authentic and has not been tampered with.

Key Functions​

This section provides a function-wise breakdown of the primary methods available in the randomness-js SDK.

Initialization Methods​

Randomness.createFromChainId() & Randomness.create[NetworkName]()​

These static methods are used to initialize the SDK and create a Randomness instance configured for a specific blockchain.

  • Randomness.createFromChainId(wallet, chainId): The primary method for creating an instance. It requires an ethers Wallet object to sign transactions and the chainId of the target network.
  • Randomness.create[NetworkName](wallet): For convenience, the SDK provides helper methods for supported networks (e.g., createBaseSepolia). These are shortcuts that pre-configure the chainId.
import { Randomness } from "randomness-js";
import { JsonRpcProvider, Wallet } from "ethers";

// Set up your ethers provider and wallet
const rpc = new JsonRpcProvider("https://api.calibration.node.glif.io/rpc/v1");
const wallet = new Wallet("<YOUR_PRIVATE_KEY>", rpc);

// Create an instance using a helper for Base Sepolia
const randomnessForBase = Randomness.createBaseSepolia(wallet);

// Or, create an instance using a chain ID for any supported network
const randomnessForChain = Randomness.createFromChainId(wallet, 314159); // Example: Filecoin Calibration

Requesting Randomness​

requestRandomness()​

This is the core action function used to send a transaction to the RandomnessSender contract to request a new random number.

This function is asynchronous and returns a Promise that resolves with a response object containing the transaction details and the resulting randomness data.

// Assuming 'randomness' is an initialized Randomness instance
const response = await randomness.requestRandomness();

console.log(response); // Contains transaction and randomness data

Verifying Randomness​

verify()​

This function provides a client-side method to cryptographically verify the authenticity of the randomness returned by the requestRandomness() call. While the on-chain contracts perform their own verification, this step is recommended for complete end-to-end security.

The function can be used in two modes:

  1. Strict Mode (Default): Throws an error if verification fails. This is useful for stopping execution immediately if the data is invalid.
  2. Flexible Mode: By passing an options object { shouldBlowUp: false }, the function will return a boolean (true or false) instead of throwing an error. This is ideal for conditional logic in your UI or backend.
// 'response' is the object from the requestRandomness() call

// 1. Strict mode: will throw an error on failure
try {
    await randomness.verify(response);
    console.log("Verification successful!");
} catch (error) {
    console.error("Verification failed:", error.message);
}

// 2. Flexible mode: returns true or false
const isVerified = await randomness.verify(response, { shouldBlowUp: false });

if (isVerified) {
    console.log("The random value is authentic.");
} else {
    console.log("The random value could not be verified.");
}

The source code for the SDK, including information on contributions, can be found in the JavaScript Library GitHub Repository