Integrate in ~10 lines.

Quickstart

Inherit EntropyConsumer, request with _roll, and implement _onRandomness. The user signs only play(); a keeper (or anyone) settles it and your callback fires.

import "./EntropyConsumer.sol";
import "./EntropyLib.sol";            // optional: many values from one reveal

contract MyGame is EntropyConsumer {
    using EntropyLib for uint256;
    uint32 constant CB_GAS = 150_000;
    mapping(uint256 => address) public player;

    constructor(address entropyV2) EntropyConsumer(entropyV2) {}

    // user signs ONCE here; pass the protocol fee through
    function play() external payable {
        require(msg.value >= entropy.fee(CB_GAS), "fee");
        uint256 id = _roll(keccak256(abi.encodePacked(msg.sender, block.number)), CB_GAS);
        player[id] = msg.sender;
    }

    // fires later when revealed (by a keeper / the next user / anyone)
    function _onRandomness(uint256 id, uint256 rng) internal override {
        uint256 pocket = rng.pick(0, 37);   // 0..36, domain-separated
        // ... settle / pay out / mint to player[id] ...
    }
}

Addresses & config

V2 is the commercial service (gas-scaled fee, sign-once UX), built on the same blockhash commit–reveal primitive.

Solidity SDK — the base handles the dangerous parts

Inherit EntropyConsumer and you get all of this for free:

You implement exactly one function: _onRandomness(uint256 id, uint256 rng).

Contract functions (DurianEntropyV2)

Frontend SDK (JS) — request, then settle with a user fallback

The one rule: never depend solely on the keeper. settle() pings the keeper, watches for the result, and if the keeper is silent it falls back to a user-signed seal+reveal.

import { DurianEntropy } from "./durian-entropy.js";

const entropy = new DurianEntropy({
  address: "0xE2BACB42Ce5C5C1FB32335ac06B79bE28fb54caB",
  workerUrl: "https://durian-entropy-keeper.pupkaikub.workers.dev/reveal",
  provider,                                  // ethers read provider
});

// 1) user signs ONE tx — your dapp's play()/mint()
const rc = await (await myGame.connect(signer).play({ value: await entropy.fee(150000) })).wait();
const id = entropy.idFromReceipt(rc);

// 2) keeper-first, user-fallback — always settles within the window
const rng = await entropy.settle(id, {
  signer,
  onState: (s) => setStatus(s),       // 'settling'→('fallback'→'sealing'→'revealing'→)'done'
});

Keeper API — POST /reveal

The Durian keeper is a Cloudflare Worker. Your frontend pings it right after the request tx; it settles on-ping as soon as the reveal block is mined (~6–9s). It is gated — it verifies the id on-chain before acting, so it can't be spammed into wasting gas. You normally never call it directly (settle() does).

POST https://durian-entropy-keeper.pupkaikub.workers.dev/reveal
Content-Type: application/json

{ "id": "<request id as decimal string>" }

Fees & cbGas

fee(cbGas) ≈ one reveal's gas × markup (currently 2×), tracked to the live gas price with a floor. Read it live and send it with the request. Overpay is safe — refund the remainder in your consumer.

Too low → the on-reveal callback fails (caught), and settle(id) recovers it in one extra tx (no fund loss). Ceiling 8,000,000. The fee funds the keeper + the Durian treasury (the fee recipient is an Ownable2Step owner — the only privileged role; it cannot touch randomness, escrows, or pause).

Seal → claim anytime

The EVM keeps only the last 256 blockhashes, so the entropy must be captured within 256 blocks — a hard limit, not a choice. seal(id) stores blockhash(revealBlock) in one cheap SSTORE inside that window; once sealed, reveal(id) (compute + callback) has no deadline — a winner claims whenever. The keeper's only time-critical job is the trivial, batchable seal.

If nobody seals within 256 blocks the request expires and is forfeit (the requester already escrowed). Extending the window is impossible and would be a re-roll exploit, so it is deliberately not done.

Rules every MONEY consumer MUST follow

Lifecycle & errors

request ──(block N+1 mined)──> WAITING ─> READY ──(seal <=256 blk)──> READY (forever) ─> FULFILLED
                                            └─(no seal, 256 blk pass)──> EXPIRED (forfeit)

Reference consumers to copy: CoinFlipHouse.sol (money game), RandomTierNFT.sol, RouletteConsumer.sol. Full guide: download the SDK (.md).