Randomness Smart Contracts

Welcome to the core concepts guide for the randomness-solidity library. To effectively use this library, it's important to understand the roles of the key smart contracts provided by Randamu. These contracts work together to provide a secure and verifiable way to get on-chain randomness powered by the dcipher threshold network.

Overview

This guide is split into two main sections:

The Randomness Contracts

The primary contracts you will use to request and receive random numbers. These contracts handle the core functionality of generating and verifying on-chain randomness.

The Signature Contracts

The underlying cryptographic foundation that makes the randomness possible. These contracts provide the secure threshold signature infrastructure.

Generating and Receiving Randomness

The randomness functionality in Randamu is built around two core contracts that work together to generate and verify randomness using conditional threshold signatures from the dcipher network.

RandomnessSender.sol

An abstract contract that serves as the foundation for any smart contract that needs to request and receive verifiable randomness. You do not need to deploy this contract yourself; you will interact with an instance already deployed by Randamu on your chosen network.

💡 Check out the available networks here

Primary Responsibilities:

Responsibility	Description
Handling Requests	Receives all incoming requests for random numbers from various user contracts
Managing Communication	Securely communicates with the off-chain dcipher threshold network
Processing Results	Processes signed results from the dcipher network to produce verifiable random values
Delivering Randomness	Sends the final random number back to your contract via callback

In essence, this contract orchestrates the entire process, acting as the robust and secure intermediary between your application and the powerful dcipher network.

RandomnessReceiverBase.sol

This is an abstract contract that serves as a template for your implementation. To receive randomness, your smart contract must inherit from RandomnessReceiverBase.sol.

Key Functionality:

1. Request Functionality:

   • Provides access to the internal _requestRandomnessPayInNative() and _requestRandomnessWithSubscription() functions
   • Includes variants for payment handling

2. Required Callback:

   • Defines onRandomnessReceived(uint256 requestId, bytes32 _randomness) function
   • Must be implemented in your contract
   • Called by RandomnessSender to deliver secure random values

Randomness Request Lifecycle

The process of requesting and receiving randomness follows these key steps:

1. Initiate Request

Your contract, which extends RandomnessReceiverBase, begins the process by invoking _requestRandomnessPayInNative() or _requestRandomnessWithSubscription() function.

2. Relay to RandomnessSender

This call is forwarded to the deployed RandomnessSender contract, acting as the bridge to the randomness provider.

3. Interaction with dcipher Network

The RandomnessSender engages with the dcipher network to securely retrieve a verifiable random number.

4. Callback with Randomness

Once the random value is verified, RandomnessSender invokes onRandomnessReceived() on your contract, delivering the final random result.

💡 Note: Each step in this process is secured by the underlying threshold signature scheme, ensuring the randomness is both verifiable and tamper-proof.

The Cryptographic Foundation - Signatures

The randomness generated by the network is fundamentally derived from conditional threshold signatures. The library exposes the underlying contracts for requesting signatures directly, providing insight into the security and modularity of the system.

Core Signature Contracts

Contract	Description
SignatureSender.sol	Core contract for managing conditional threshold signing of messages using the dcipher network
SignatureReceiverBase.sol	An abstract contract for requesting and receiving threshold signatures from the dcipher network
SignatureSchemeAddressProvider.sol	Maintains the list of supported signature schemes (e.g., BLS)

💡 Note: These contracts form the cryptographic foundation that enables secure and verifiable randomness generation. You only need to extend RandomnessReceiverBase.sol to customize randomness requests. All other required contracts are already deployed on supported networks.