@d20dao/vrf-sdk 0.1.0

package/contracts/D20VRFConsumer.sol

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {ID20VRFConsumer, ID20VRFRefundConsumer} from "./interfaces/ID20VRF.sol";
+
+/// @notice Every consumer must authenticate callbacks before changing application state.
+abstract contract D20VRFConsumer is ID20VRFConsumer, ID20VRFRefundConsumer {
+    address public immutable vrfCoordinator;
+    error OnlyCoordinator();
+    error InvalidCoordinator();
+
+    constructor(address coordinator) {
+        if (coordinator.code.length == 0) revert InvalidCoordinator();
+        vrfCoordinator = coordinator;
+    }
+
+    function rawFulfillRandomness(uint256 requestId, bytes32 randomness) external {
+        if (msg.sender != vrfCoordinator) revert OnlyCoordinator();
+        _fulfillRandomness(requestId, randomness);
+    }
+
+    function onRefund(uint256 requestId) external {
+        if (msg.sender != vrfCoordinator) revert OnlyCoordinator();
+        _onRefund(requestId);
+    }
+
+    /// @dev Optional lifecycle notification. Funds may be paid to a different refundAddress
+    ///      or held as credit. Correlate the request and handle application refunds separately.
+    function _onRefund(uint256 requestId) internal virtual {}
+
+    /// @dev Store randomness only. Keep minting and transfers out of the callback.
+    function _fulfillRandomness(uint256 requestId, bytes32 randomness) internal virtual;
+}

package/contracts/examples/MiningRandomnessConsumer.sol

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {D20VRFConsumer} from "../D20VRFConsumer.sol";
+import {ID20VRF} from "../interfaces/ID20VRF.sol";
+
+/// @notice Integration building block, not a replacement for the game's mining/economy contracts.
+/// @dev The actual game validates PoW, locks payment and immutable claim attributes BEFORE
+///      calling _requestForClaim inside that same transaction. No user reveal/contribution call.
+abstract contract MiningRandomnessConsumer is D20VRFConsumer {
+    struct ClaimRandomness { uint256 requestId; bytes32 randomness; bool requested; bool ready; }
+    mapping(uint256 => ClaimRandomness) public claimRandomness;
+    mapping(uint256 => uint256) public requestToClaim;
+    mapping(uint256 => bool) private knownRequest;
+    event ClaimRandomnessRequested(uint256 indexed claimId, uint256 indexed requestId);
+    event ClaimReady(uint256 indexed claimId, uint256 indexed requestId, bytes32 randomness);
+    error ClaimAlreadyRequested();
+    error UnexpectedCallback();
+    error ClaimNotReady();
+    error InvalidCandidate();
+
+    constructor(address coordinator) D20VRFConsumer(coordinator) {}
+
+    function _requestForClaim(uint256 claimId, bytes32 lockedWork, uint32 callbackGasLimit, address refundAddress)
+        internal returns (uint256 requestId)
+    {
+        if (claimRandomness[claimId].requested) revert ClaimAlreadyRequested();
+        claimRandomness[claimId].requested = true;
+        ID20VRF rng = ID20VRF(vrfCoordinator);
+        requestId = rng.requestRandomness{value: rng.requestFee()}(
+            keccak256(abi.encode(claimId, lockedWork)), callbackGasLimit, refundAddress
+        );
+        claimRandomness[claimId].requestId = requestId;
+        requestToClaim[requestId] = claimId;
+        knownRequest[requestId] = true;
+        emit ClaimRandomnessRequested(claimId, requestId);
+    }
+
+    function _fulfillRandomness(uint256 requestId, bytes32 randomness) internal override {
+        if (!knownRequest[requestId]) revert UnexpectedCallback();
+        uint256 claimId = requestToClaim[requestId];
+        ClaimRandomness storage claim = claimRandomness[claimId];
+        if (claim.ready) revert UnexpectedCallback();
+        claim.randomness = randomness;
+        claim.ready = true;
+        emit ClaimReady(claimId, requestId, randomness);
+    }
+
+    function candidateSeed(uint256 claimId, uint8 candidate) public view returns (bytes32) {
+        ClaimRandomness storage claim = claimRandomness[claimId];
+        if (!claim.ready) revert ClaimNotReady();
+        if (candidate >= 3) revert InvalidCandidate();
+        return keccak256(abi.encode(
+            keccak256("VRF_D20DAO_CARD_V1"), block.chainid, address(this),
+            claimId, claim.requestId, claim.randomness, candidate
+        ));
+    }
+}

package/contracts/interfaces/ID20VRF.sol

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {RandomnessMapping} from "../libraries/RandomnessMapping.sol";
+
+interface ID20VRF {
+    function requestFee() external view returns (uint256);
+    function requestRandomness(bytes32 clientSeed, uint32 callbackGasLimit, address _refundAddress)
+        external payable returns (uint256 requestId);
+    function requestMappedRandomness(
+        bytes32 clientSeed, uint32 callbackGasLimit, address _refundAddress, RandomnessMapping.Spec calldata spec
+    ) external payable returns (uint256 requestId);
+    function getMappedResult(uint256 requestId) external view returns (uint256[] memory);
+}
+
+interface ID20VRFConsumer {
+    function rawFulfillRandomness(uint256 requestId, bytes32 randomness) external;
+}
+
+/// @notice Optional notification after the RNG fee was refunded or recorded as backed credit.
+interface ID20VRFRefundConsumer {
+    function onRefund(uint256 requestId) external;
+}

package/contracts/libraries/D20VRFRequests.sol

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {ID20VRF} from "../interfaces/ID20VRF.sol";
+import {RandomnessMapping as M} from "./RandomnessMapping.sol";
+
+/// @notice Built-in request helpers for game contracts. All requests still callback with (id, rawWord).
+/// @dev Usage: using D20VRFRequests for ID20VRF; rng.d20(options). Inspect getMappedResult(id) after fulfillment.
+library D20VRFRequests {
+    struct Options { bytes32 clientSeed; uint32 callbackGasLimit; address refundAddress; }
+    function diceRoll(ID20VRF rng, uint256 sides, uint32 count, Options memory o) internal returns (uint256) {
+        return _send(rng, M.Spec(M.Operation.DiceRoll, 0, sides, count, 0), o);
+    }
+    function dN(ID20VRF rng, uint256 sides, Options memory o) internal returns (uint256) {
+        return diceRoll(rng, sides, 1, o);
+    }
+    function d20(ID20VRF rng, Options memory o) internal returns (uint256) { return dN(rng, 20, o); }
+    function d12(ID20VRF rng, Options memory o) internal returns (uint256) { return dN(rng, 12, o); }
+    function d10(ID20VRF rng, Options memory o) internal returns (uint256) { return dN(rng, 10, o); }
+    function d8(ID20VRF rng, Options memory o) internal returns (uint256) { return dN(rng, 8, o); }
+    function d6(ID20VRF rng, Options memory o) internal returns (uint256) { return dN(rng, 6, o); }
+    function d4(ID20VRF rng, Options memory o) internal returns (uint256) { return dN(rng, 4, o); }
+    function coinFlip(ID20VRF rng, Options memory o) internal returns (uint256) {
+        return _send(rng, M.Spec(M.Operation.CoinFlip, 0, 0, 1, 0), o);
+    }
+    function numberRange(ID20VRF rng, uint256 min, uint256 max, Options memory o) internal returns (uint256) {
+        return _send(rng, M.Spec(M.Operation.NumberRange, min, max, 1, 0), o);
+    }
+    function chooseOne(ID20VRF rng, uint32 population, Options memory o) internal returns (uint256) {
+        return _send(rng, M.Spec(M.Operation.ChooseOne, 0, 0, 1, population), o);
+    }
+    function chooseMany(ID20VRF rng, uint32 population, uint32 count, Options memory o) internal returns (uint256) {
+        return _send(rng, M.Spec(M.Operation.ChooseMany, 0, 0, count, population), o);
+    }
+    function shuffle(ID20VRF rng, uint32 population, Options memory o) internal returns (uint256) {
+        return _send(rng, M.Spec(M.Operation.Shuffle, 0, 0, population, population), o);
+    }
+    function _send(ID20VRF rng, M.Spec memory spec, Options memory o) private returns (uint256) {
+        return rng.requestMappedRandomness{value: rng.requestFee()}(o.clientSeed, o.callbackGasLimit, o.refundAddress, spec);
+    }
+}

package/contracts/libraries/RandomnessMapping.sol

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+/// @notice Version 1 deterministic, unbiased range sampling and bounded game operations.
+/// @dev Choice/shuffle outputs are indices. Consumers must lock their item list before requesting.
+library RandomnessMapping {
+    enum Operation { Raw, DiceRoll, CoinFlip, NumberRange, ChooseOne, ChooseMany, Shuffle }
+    struct Spec {
+        Operation operation;
+        uint256 lower;
+        uint256 upper;
+        uint32 count;
+        uint32 population;
+    }
+    struct Stream { bytes32 randomness; uint256 cursor; }
+    bytes32 internal constant MAP_DOMAIN = keccak256("D20_MAP");
+    uint32 internal constant MAX_ITEMS = 256;
+    uint32 internal constant MAX_DICE = 128;
+    error InvalidMapping();
+
+    function validate(Spec memory s) internal pure {
+        if (s.operation == Operation.Raw) {
+            if (s.lower != 0 || s.upper != 0 || s.count != 0 || s.population != 0) revert InvalidMapping();
+        } else if (s.operation == Operation.DiceRoll) {
+            if (s.lower != 0 || s.upper < 2 || s.count == 0 || s.count > MAX_DICE || s.population != 0)
+                revert InvalidMapping();
+        } else if (s.operation == Operation.CoinFlip) {
+            if (s.lower != 0 || s.upper != 0 || s.count != 1 || s.population != 0) revert InvalidMapping();
+        } else if (s.operation == Operation.NumberRange) {
+            if (s.lower > s.upper || s.count != 1 || s.population != 0) revert InvalidMapping();
+        } else {
+            if (s.lower != 0 || s.upper != 0 || s.population == 0 || s.population > MAX_ITEMS)
+                revert InvalidMapping();
+            if (s.operation == Operation.ChooseOne && s.count != 1) revert InvalidMapping();
+            if (s.operation == Operation.ChooseMany && (s.count == 0 || s.count > s.population))
+                revert InvalidMapping();
+            if (s.operation == Operation.Shuffle && s.count != s.population) revert InvalidMapping();
+        }
+    }
+
+    function hash(Spec memory s) internal pure returns (bytes32) {
+        return keccak256(abi.encode(s.operation, s.lower, s.upper, s.count, s.population));
+    }
+
+    function map(bytes32 randomness, Spec memory s) internal pure returns (uint256[] memory result) {
+        validate(s);
+        Stream memory stream = Stream(randomness, 0);
+        if (s.operation == Operation.Raw) {
+            result = new uint256[](1);
+            result[0] = uint256(randomness);
+        } else if (s.operation == Operation.DiceRoll) {
+            result = new uint256[](s.count);
+            for (uint256 i; i < s.count; ++i) result[i] = sample(stream, s.upper) + 1;
+        } else if (s.operation == Operation.CoinFlip) {
+            result = new uint256[](1);
+            result[0] = sample(stream, 2); // 0 = tails, 1 = heads.
+        } else if (s.operation == Operation.NumberRange) {
+            result = new uint256[](1);
+            result[0] = s.lower == 0 && s.upper == type(uint256).max
+                ? next(stream) : s.lower + sample(stream, s.upper - s.lower + 1);
+        } else if (s.operation == Operation.ChooseOne) {
+            result = new uint256[](1);
+            result[0] = sample(stream, s.population);
+        } else {
+            // Partial Fisher-Yates: without-replacement choices, or a full permutation.
+            uint256[] memory pool = new uint256[](s.population);
+            for (uint256 i; i < s.population; ++i) pool[i] = i;
+            result = new uint256[](s.count);
+            for (uint256 i; i < s.count; ++i) {
+                uint256 j = i + sample(stream, s.population - i);
+                (pool[i], pool[j]) = (pool[j], pool[i]);
+                result[i] = pool[i];
+            }
+        }
+    }
+
+    function next(Stream memory stream) internal pure returns (uint256) {
+        return uint256(keccak256(abi.encode(MAP_DOMAIN, stream.randomness, stream.cursor++)));
+    }
+
+    /// @dev Reject the short residue prefix instead of introducing modulo bias.
+    function sample(Stream memory stream, uint256 bound) internal pure returns (uint256) {
+        uint256 threshold;
+        unchecked { threshold = (0 - bound) % bound; }
+        uint256 word;
+        do { word = next(stream); } while (word < threshold);
+        return word % bound;
+    }
+}