Quickstart

A consumer contract needs three things: forward the fee with a request, inherit the consumer base, and implement one callback. Complete working example:

// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.8.20;

import {IDicedEntropy} from "diced/IDicedEntropy.sol";
import {IDicedConsumer} from "diced/IDicedConsumer.sol";

contract CoinFlip is IDicedConsumer {
    IDicedEntropy public immutable entropy;

    event FlipResult(uint64 indexed seq, bool heads);

    constructor(address entropy_) { entropy = IDicedEntropy(entropy_); }

    function flip(bytes32 userRandom) external payable returns (uint64 seq) {
        // send at least getFeeV2(); any surplus is credited back to you
        seq = entropy.request{value: msg.value}(userRandom, 0);
    }

    function getEntropy() internal view override returns (address) {
        return address(entropy);
    }

    function entropyCallback(uint64 seq, address, bytes32 randomNumber) internal override {
        emit FlipResult(seq, uint256(randomNumber) & 1 == 0);
    }
}

Map the 32-byte word onto your outcome space with modulo arithmetic (uint256(randomNumber) % sides). One word is enough for many sub-outcomes — slice bits or re-hash with a domain separator.

Without a contract

You can request from an ordinary account, which is what the demo on the home page does. Send requestV2() to the oracle with getFeeV2() attached, then read the word out of the Revealed event rather than a callback — an EOA has no code to call back into, so the oracle's delivery call is a harmless no-op and callbackSucceeded comes back true.

// 1. fee, 2. request, 3. read the word off the event
const fee = await entropy.read.getFeeV2();
const hash = await entropy.write.requestV2({ value: fee });
const receipt = await client.waitForTransactionReceipt({ hash });

// sequenceNumber is topic 2 of Requested; watch Revealed for the same one
const logs = await client.getLogs({
  address: ORACLE, fromBlock: receipt.blockNumber,
  event: parseAbiItem('event Revealed(address indexed provider, uint64 indexed sequenceNumber, address indexed requester, bytes32 randomNumber, bool callbackSucceeded)'),
  args: { sequenceNumber: seq },
});
const word = logs[0].args.randomNumber;

Addresses

API reference

Requesting

Reading

Refunds

refundRequest(uint64 seq) — callable by anyone once a request has been pending longer than the refund delay (10 minutes at launch). The fee returns to the original requester in the original token, always. Native-fee consumers must be able to receive ETH (have a receive()), or use WETH.

Events

event Requested(uint64 indexed sequenceNumber, address indexed requester,
                address feeToken, uint96 feePaid, uint32 callbackGasLimit, bytes32 userContribution);
event Revealed(uint64 indexed sequenceNumber, address indexed requester,
               bytes32 randomNumber, bool callbackSucceeded);
event CallbackFailed(uint64 indexed sequenceNumber, address indexed requester,
                     bytes32 randomNumber, bytes reason);
event Refunded(uint64 indexed sequenceNumber, address indexed requester,
               address feeToken, uint96 amount);

The callback

• Only the oracle can invoke _entropyCallback; the IDicedConsumer base enforces it. You override the internal entropyCallback.
• It runs under your requested gas limit. Keep it lean; do heavy work in a later user transaction.
• A revert in your callback does not undo the reveal. The word is stored in failedCallbackRandomness(provider, seq) and a CallbackFailed event fires — build a self-serve path if your logic can revert.
• Reveals can arrive in any order relative to other requests. Key your state by sequence number, never by "latest".

Fees & refunds lifecycle

1. Request: fee escrows inside the oracle, tied to your request.
2. Reveal: escrow becomes operator revenue — only now.
3. No reveal: after the delay, anyone triggers your refund; escrow returns to you in full.

The operator cannot withdraw escrow of pending requests — the accounting makes it impossible, not just impolite.

TypeScript

import { getFee, requestRandomness, waitForCallback } from '@diced/sdk';

const fee = await getFee(publicClient, ENTROPY);
const { sequenceNumber } = await requestRandomness(publicClient, walletClient, ENTROPY);
const { randomNumber } = await waitForCallback(publicClient, ENTROPY, sequenceNumber);

The SDK ships viem-based helpers plus the Solidity interfaces. Contact us for access while the repository is private.

Migrating from other entropy oracles

The consumer surface is deliberately Pyth-Entropy-shaped: requestV2(), the _entropyCallback(uint64, address, bytes32) selector, fee-forwarding semantics. If your contract already consumes a Pyth-style entropy service, migration is: point it at the diced.fun oracle address. The only behavioral differences to review are the flat (not gas-scaled) fee, the exact-msg.value rule, and the refund flow above.

Trust model

What is cryptographically guaranteed, and what you still take on trust. No hand-waving.

Guaranteed

• No grinding. The provider's hash chain is committed on-chain before your request; your contribution lands before the reveal. The word is keccak256(providerReveal, yourContribution, seq, you) — neither side alone chooses it.
• Verifiability. Every reveal is keccak-verified on-chain against the commitment; anyone can recompute every delivered word from public data.
• Isolation. Other consumers' reverting or gas-hungry callbacks cannot affect your delivery.
• Refundability. An unrevealed request is always refundable, permissionlessly. Funds cannot be stuck.

Taken on trust

• Withholding. The provider knows future reveals and could decline to publish one, converting an outcome into a refund. It cannot substitute a different outcome. Design your application so refund-instead-of-delivery is an acceptable worst case.
• Provider participation. Knowing its future reveals, the provider could act as a user of your downstream application with a chosen contribution. Relevant only if you don't trust the operator; visible on-chain if it happens; not cryptographically prevented in any single-provider design.
• Liveness. One keeper serves reveals (1–3s typical). Downtime means delayed delivery, then refunds — never stuck funds.