Integrate in ~10 lines.

Quickstart

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

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

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

    constructor(address entropyV2) EntropyConsumerV21(entropyV2) {}

    // user signs ONCE. Fund this tx from the frontend with entropy.feeAndGas() (over-funds gas = no "fee" revert)
    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 EntropyConsumerV21 and you get all of this for free:

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

Contract functions (DurianEntropyV21)

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: "0xa32236611eC11980B1F15760eB3432f7e25EFdC8",
  workerUrl: "https://keeper-v21.durianfun.xyz/reveal",
  provider,                                  // ethers read provider
});

// 1) user signs ONE tx. Use feeAndGas() (NOT fee()): it OVER-funds (2× gas) + does NOT pin gasPrice,
//    so a wallet gas-bump can't revert "fee". The contract refunds the surplus (your consumer refunds
//    it on the consumer path; reclaim() on the direct path). Never send the exact fee().
const rc = await (await myGame.connect(signer).play({ ...(await entropy.feeAndGas(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://keeper-v21.durianfun.xyz/reveal
Content-Type: application/json

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

Fees & cbGas

fee(cbGas) = bounty + protocol. bounty = (bountyGas + cbGas) × gasprice reimburses whoever reveals (a self-funding keeper market); protocol = bounty × protocolBps/10000 (currently 100% ⇒ fee = 2× bounty) is Durian revenue. Tracked to the live gas price with a floor. Fund a request with entropy.feeAndGas(cbGas) — never send the exact fee(). The fee is computed from tx.gasprice at execution and wallets override the gas price you set (seen live: Rabby bumps 25→30 gwei), so an exact fee reverts "fee". feeAndGas over-funds at 2× gas and does not pin gasPrice; the contract charges only the real fee and refunds the surplus — reclaim() on the direct path, or your consumer refunds the overpay (RouletteHouse does).

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: CoinFlipHouseV21.sol (money game), RandomTierNFTV21.sol, RouletteConsumerV21.sol. Full guide: download the SDK (.md).