Add Randoo to a game

curl -sS https://randoo.xyz/randoo.json -o randoo.json
jq -r '.networks.saigon | .coordinator, .chainId, .rpc, .implementation' randoo.json

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {IRoninVRFCoordinatorForConsumers} from "./interfaces/IRoninVRFCoordinatorForConsumers.sol";

/// @notice Ronin VRFConsumer-shaped base. Swap coordinator address to migrate.
abstract contract RandooConsumerRonin {
    error OnlyCoordinatorCanFulfill();

    address public vrfCoordinator;

    constructor(address vrfCoordinator_) {
        vrfCoordinator = vrfCoordinator_;
    }

    function rawFulfillRandomSeed(bytes32 reqHash, uint256 randomSeed) external {
        if (msg.sender != vrfCoordinator) revert OnlyCoordinatorCanFulfill();
        _fulfillRandomSeed(reqHash, randomSeed);
    }

    function _fulfillRandomSeed(bytes32 reqHash, uint256 randomSeed) internal virtual;

    function _requestRandomness(
        uint256 value,
        uint256 callbackGasLimit,
        uint256 gasPriceToFulfill,
        address refundAddr
    ) internal returns (bytes32 reqHash) {
        reqHash = IRoninVRFCoordinatorForConsumers(vrfCoordinator).requestRandomSeed{value: value}(
            callbackGasLimit, gasPriceToFulfill, address(this), refundAddr
        );
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

// ---------------------------------------------------------------------------
// Randoo consumer template: copy-pasteable as a unit with
// RandooConsumerTemplate.t.sol and MockRandooCoordinator.sol (this folder), plus
// src/RandooConsumerRonin.sol and src/interfaces/IRoninVRFCoordinatorForConsumers.sol.
// Imports resolve in a fresh `forge init` with only forge-std installed.
// ---------------------------------------------------------------------------

import {RandooConsumerRonin} from "../../src/RandooConsumerRonin.sol";

/// @notice The canonical Randoo consumer. Copy it, rename it, put your game
///         logic in `_fulfillRandomSeed`.
///
/// Flow: a caller pays `estimateRequestRandomFee(callbackGasLimit, gasPrice)`
/// into `roll`, which forwards the request to the coordinator and returns the
/// `reqHash`. Later the coordinator calls `rawFulfillRandomSeed` (inherited,
/// coordinator-only) which lands in `_fulfillRandomSeed` with the seed.
contract TemplateConsumer is RandooConsumerRonin {
    /// @notice Last seed delivered by the coordinator.
    uint256 public lastSeed;
    /// @notice Request hash of the most recent `roll`, then of the most recent fulfil.
    bytes32 public lastReqHash;

    constructor(address vrfCoordinator_) RandooConsumerRonin(vrfCoordinator_) {}

    /// @param callbackGasLimit Gas the coordinator will give `_fulfillRandomSeed` (50k..2.5M).
    /// @param gasPrice Gas price the fulfiller may spend; must be >= the coordinator floor.
    /// @param refundAddr Receives unspent fulfilment gas; must be non-zero.
    function roll(uint256 callbackGasLimit, uint256 gasPrice, address refundAddr)
        external
        payable
        returns (bytes32 reqHash)
    {
        reqHash = _requestRandomness(msg.value, callbackGasLimit, gasPrice, refundAddr);
        lastReqHash = reqHash;
    }

    /// @dev Your randomness lands here. Keep it within `callbackGasLimit`.
    function _fulfillRandomSeed(bytes32 reqHash, uint256 randomSeed) internal override {
        lastReqHash = reqHash;
        lastSeed = randomSeed;
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

/// @dev Byte-compatible with Ronin VRF's consumer-facing coordinator.
interface IRoninVRFCoordinatorForConsumers {
    function requestRandomSeed(
        uint256 callbackGasLimit,
        uint256 gasPrice,
        address consumer,
        address refundAddress
    ) external payable returns (bytes32 reqHash);

    function estimateRequestRandomFee(uint256 callbackGasLimit, uint256 gasPrice)
        external
        view
        returns (uint256);
}

interface IRoninVRFConsumer {
    function rawFulfillRandomSeed(bytes32 reqHash, uint256 randomSeed) external;
}

cast call 0xC66eB2e7EE91145875000Ad46B55600000000001 "estimateRequestRandomFee(uint256,uint256)(uint256)" 250000 25000000000 --rpc-url https://saigon-testnet.roninchain.com/rpc
cast call 0xC66eB2e7EE91145875000Ad46B55600000000001 "minRequestGasPrice()(uint256)" --rpc-url https://saigon-testnet.roninchain.com/rpc

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

// ---------------------------------------------------------------------------
// Randoo consumer template: copy-pasteable as a unit with
// RandooConsumerTemplate.t.sol and TemplateConsumer.sol (this folder), plus
// src/RandooConsumerRonin.sol and src/interfaces/IRoninVRFCoordinatorForConsumers.sol.
// Imports resolve in a fresh `forge init` with only forge-std installed.
// ---------------------------------------------------------------------------

import {
    IRoninVRFCoordinatorForConsumers,
    IRoninVRFConsumer
} from "../../src/interfaces/IRoninVRFCoordinatorForConsumers.sol";

/// @notice Test double for the Randoo VRF coordinator.
///
/// `requestRandomSeed` performs the same checks, in the same order, with the
/// same custom error names and the same gas-price buffer as the live
/// coordinator, so a consumer that passes against this mock will not be
/// surprised on-chain. `fulfil` delivers a seed the way the live fulfiller
/// does: exactly once per request (`AlreadyFulfilled` on a retry), via a
/// bounded-gas low-level call whose failure is reported, never propagated
/// (the Chainlink `VRFCoordinatorV2Mock` pattern).
///
/// Not reproduced: the USD-pegged service fee (a flat `fixedFee` stands in),
/// the oracle set, confirmations, and refund accounting.
contract MockRandooCoordinator is IRoninVRFCoordinatorForConsumers {
    // Same names as RandooVRFCoordinator so `vm.expectRevert(Mock.X.selector)`
    // matches what the real contract would throw.
    error CallerIsNotConsumer();
    error InvalidRefund();
    error GasLimit();
    error InvalidGasPrice();
    error InsufficientFee();
    error UnknownRequest();
    error AlreadyFulfilled();

    /// @dev Same shape as the live coordinator's event.
    event RandomSeedRequested(
        bytes32 indexed reqHash,
        uint256 indexed requestId,
        address indexed consumer,
        uint256 callbackGasLimit,
        uint256 gasPrice,
        address refundAddress,
        uint256 prepaid
    );
    /// @dev Same shape as the live coordinator's event. The mock does no fee
    ///      accounting, so `payment`, `fee`, and `refund` are always 0 here.
    event RandomSeedFulfilled(
        bytes32 indexed reqHash,
        uint256 indexed requestId,
        uint256 seed,
        uint256 payment,
        uint256 fee,
        uint256 refund,
        bool callbackOk
    );

    // Live coordinator bounds.
    uint256 public constant MIN_CALLBACK_GAS = 50_000;
    uint256 public constant MAX_CALLBACK_GAS = 2_500_000;
    /// @dev Gas the fulfiller spends around the callback; priced into every quote.
    uint256 public constant ADDITIONAL_GAS = 500_000;
    uint256 public constant BPS = 10_000;

    /// @notice Flat service fee added to every quote. Settable for tests.
    uint256 public fixedFee = 0.05 ether;
    /// @notice Floor the BUFFERED `gasPrice` must reach. Settable for tests.
    uint256 public minGasPrice = 21 gwei;
    /// @notice Live default: the coordinator marks every `gasPrice` up by 10 %
    ///         before the floor check and the fee; the quote includes it.
    uint16 public gasPriceBufferBps = 1000;

    uint256 public requestNonce;
    bytes32 public lastReqHash;
    mapping(bytes32 => address) public consumerOf;
    mapping(bytes32 => uint256) public requestIdOf;
    mapping(bytes32 => uint256) public callbackGasLimitOf;
    mapping(bytes32 => bool) public fulfilled;

    function setFixedFee(uint256 fee) external {
        fixedFee = fee;
    }

    function setMinGasPrice(uint256 price) external {
        minGasPrice = price;
    }

    function setGasPriceBufferBps(uint16 bps) external {
        gasPriceBufferBps = bps;
    }

    /// @notice The live coordinator's `_bufferedGasPrice`, same arithmetic.
    function bufferedGasPrice(uint256 gasPrice) public view returns (uint256) {
        return gasPrice + (gasPrice * gasPriceBufferBps) / BPS;
    }

    /// @inheritdoc IRoninVRFCoordinatorForConsumers
    function estimateRequestRandomFee(uint256 callbackGasLimit, uint256 gasPrice)
        public
        view
        returns (uint256)
    {
        return fixedFee + bufferedGasPrice(gasPrice) * (callbackGasLimit + ADDITIONAL_GAS);
    }

    /// @inheritdoc IRoninVRFCoordinatorForConsumers
    function requestRandomSeed(
        uint256 callbackGasLimit,
        uint256 gasPrice,
        address consumer,
        address refundAddress
    ) external payable returns (bytes32 reqHash) {
        if (callbackGasLimit < MIN_CALLBACK_GAS || callbackGasLimit > MAX_CALLBACK_GAS) revert GasLimit();
        if (msg.sender != consumer) revert CallerIsNotConsumer();
        if (refundAddress == address(0)) revert InvalidRefund();
        gasPrice = bufferedGasPrice(gasPrice);
        if (gasPrice == 0 || gasPrice < minGasPrice) revert InvalidGasPrice();
        if (msg.value < fixedFee + gasPrice * (callbackGasLimit + ADDITIONAL_GAS)) revert InsufficientFee();

        uint256 requestId = ++requestNonce;
        reqHash = keccak256(abi.encode(address(this), requestId, consumer, block.number));
        lastReqHash = reqHash;
        consumerOf[reqHash] = consumer;
        requestIdOf[reqHash] = requestId;
        callbackGasLimitOf[reqHash] = callbackGasLimit;

        emit RandomSeedRequested(
            reqHash, requestId, consumer, callbackGasLimit, gasPrice, refundAddress, msg.value
        );
    }

    /// @notice Deliver `seed` for `reqHash` to its consumer, exactly as the live
    ///         fulfiller does: once only, bounded gas, failure reported not
    ///         propagated. A second call for the same `reqHash` reverts with
    ///         `AlreadyFulfilled` even if the first callback failed.
    /// @return success False if the consumer's callback reverted or ran out of gas.
    function fulfil(bytes32 reqHash, uint256 seed) external returns (bool success) {
        address consumer = consumerOf[reqHash];
        if (consumer == address(0)) revert UnknownRequest();
        if (fulfilled[reqHash]) revert AlreadyFulfilled();
        fulfilled[reqHash] = true;
        (success,) = consumer.call{gas: callbackGasLimitOf[reqHash]}(
            abi.encodeWithSelector(IRoninVRFConsumer.rawFulfillRandomSeed.selector, reqHash, seed)
        );
        emit RandomSeedFulfilled(reqHash, requestIdOf[reqHash], seed, 0, 0, 0, success);
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

// ---------------------------------------------------------------------------
// Randoo consumer template: copy-pasteable as a unit.
//
// This file, MockRandooCoordinator.sol, and TemplateConsumer.sol (this folder)
// plus src/RandooConsumerRonin.sol and src/interfaces/IRoninVRFCoordinatorForConsumers.sol
// are the five published files. Drop them into a fresh `forge init` project at
//
//   src/RandooConsumerRonin.sol
//   src/interfaces/IRoninVRFCoordinatorForConsumers.sol
//   test/templates/RandooConsumerTemplate.t.sol
//   test/templates/MockRandooCoordinator.sol
//   test/templates/TemplateConsumer.sol
//
// and `forge test` passes with only forge-std installed.
//
// To test YOUR consumer: replace `TemplateConsumer` at the SWAP POINT below with
// your contract (it must inherit RandooConsumerRonin and expose a payable entry
// point that calls `_requestRandomness`). The assertions stay as they are.
// ---------------------------------------------------------------------------

import {Test} from "forge-std/Test.sol";
import {RandooConsumerRonin} from "../../src/RandooConsumerRonin.sol";
import {MockRandooCoordinator} from "./MockRandooCoordinator.sol";
import {TemplateConsumer} from "./TemplateConsumer.sol";

/// @dev Consumer whose callback always reverts. Used to prove the coordinator
///      never lets a bad callback revert the fulfil transaction.
contract RevertingConsumer is RandooConsumerRonin {
    constructor(address vrfCoordinator_) RandooConsumerRonin(vrfCoordinator_) {}

    function roll(uint256 callbackGasLimit, uint256 gasPrice, address refundAddr)
        external
        payable
        returns (bytes32)
    {
        return _requestRandomness(msg.value, callbackGasLimit, gasPrice, refundAddr);
    }

    function _fulfillRandomSeed(bytes32, uint256) internal pure override {
        revert("callback failed");
    }
}

contract RandooConsumerTemplateTest is Test {
    // Same bounds and defaults as the live Randoo coordinator.
    uint256 internal constant CALLBACK_GAS = 200_000;
    uint256 internal constant GAS_PRICE = 21 gwei;

    MockRandooCoordinator internal coordinator;
    // ---- SWAP POINT: replace TemplateConsumer with your consumer contract. ----
    TemplateConsumer internal consumer;
    // ---------------------------------------------------------------------------

    address internal player = makeAddr("player");
    address internal refundTo = makeAddr("refund");

    function setUp() public {
        coordinator = new MockRandooCoordinator();
        // ---- SWAP POINT: construct your consumer with the coordinator address. ----
        consumer = new TemplateConsumer(address(coordinator));
        // ---------------------------------------------------------------------------
        vm.deal(player, 100 ether);
    }

    function _quote() internal view returns (uint256) {
        return coordinator.estimateRequestRandomFee(CALLBACK_GAS, GAS_PRICE);
    }

    // ----------------------------------------------------------------- request

    function testRequestSucceedsAndStoresReqHash() public {
        uint256 quote = _quote();
        vm.prank(player);
        bytes32 reqHash = consumer.roll{value: quote}(CALLBACK_GAS, GAS_PRICE, refundTo);

        assertTrue(reqHash != bytes32(0), "reqHash should be non-zero");
        assertEq(consumer.lastReqHash(), reqHash, "consumer should store reqHash");
        assertEq(coordinator.lastReqHash(), reqHash, "coordinator should record reqHash");
        assertEq(coordinator.consumerOf(reqHash), address(consumer), "consumer bound to reqHash");
    }

    function testZeroRefundAddressReverts() public {
        uint256 quote = _quote();
        vm.prank(player);
        vm.expectRevert(MockRandooCoordinator.InvalidRefund.selector);
        consumer.roll{value: quote}(CALLBACK_GAS, GAS_PRICE, address(0));
    }

    function testCallbackGasBelowMinReverts() public {
        uint256 gasLimit = coordinator.MIN_CALLBACK_GAS() - 1;
        uint256 quote = coordinator.estimateRequestRandomFee(gasLimit, GAS_PRICE);
        vm.prank(player);
        vm.expectRevert(MockRandooCoordinator.GasLimit.selector);
        consumer.roll{value: quote}(gasLimit, GAS_PRICE, refundTo);
    }

    function testCallbackGasAboveMaxReverts() public {
        uint256 gasLimit = coordinator.MAX_CALLBACK_GAS() + 1;
        uint256 quote = coordinator.estimateRequestRandomFee(gasLimit, GAS_PRICE);
        vm.prank(player);
        vm.expectRevert(MockRandooCoordinator.GasLimit.selector);
        consumer.roll{value: quote}(gasLimit, GAS_PRICE, refundTo);
    }

    /// @dev Live semantics: the coordinator marks `gasPrice` up by its buffer
    ///      and compares THAT to the floor. A raw price one wei under the floor
    ///      still clears it once buffered; a raw price whose buffered value is
    ///      one wei short of the floor reverts.
    function testGasPriceBelowBufferedFloorReverts() public {
        uint256 floor = coordinator.minGasPrice();
        uint256 bps = coordinator.BPS();
        uint256 buffer = coordinator.gasPriceBufferBps();

        // Highest raw price that stays under the floor after the buffer.
        uint256 lowPrice = (floor * bps) / (bps + buffer) - 1;
        assertLt(coordinator.bufferedGasPrice(lowPrice), floor, "fixture: buffered must be < floor");
        uint256 quote = coordinator.estimateRequestRandomFee(CALLBACK_GAS, lowPrice);
        vm.prank(player);
        vm.expectRevert(MockRandooCoordinator.InvalidGasPrice.selector);
        consumer.roll{value: quote}(CALLBACK_GAS, lowPrice, refundTo);

        // Raw price under the floor, buffered price at or above it: accepted.
        uint256 liftedPrice = floor - 1;
        assertGe(coordinator.bufferedGasPrice(liftedPrice), floor, "fixture: buffer lifts to floor");
        quote = coordinator.estimateRequestRandomFee(CALLBACK_GAS, liftedPrice);
        vm.prank(player);
        bytes32 reqHash = consumer.roll{value: quote}(CALLBACK_GAS, liftedPrice, refundTo);
        assertEq(consumer.lastReqHash(), reqHash);
    }

    /// @dev The quote prices the BUFFERED gas price. A consumer that computes
    ///      `fixedFee + gasPrice * (callbackGasLimit + ADDITIONAL_GAS)` itself
    ///      underpays and reverts on-chain; only the on-chain quote is correct.
    function testUnbufferedFeeIsRejected() public {
        uint256 unbuffered = coordinator.fixedFee() + GAS_PRICE * (CALLBACK_GAS + coordinator.ADDITIONAL_GAS());
        uint256 quote = _quote();
        assertGt(quote, unbuffered, "quote must include the gas-price buffer");

        vm.prank(player);
        vm.expectRevert(MockRandooCoordinator.InsufficientFee.selector);
        consumer.roll{value: unbuffered}(CALLBACK_GAS, GAS_PRICE, refundTo);
    }

    function testCallerMustBeConsumer() public {
        uint256 quote = _quote();
        // Call the coordinator directly, naming the consumer but not being it.
        vm.prank(player);
        vm.expectRevert(MockRandooCoordinator.CallerIsNotConsumer.selector);
        coordinator.requestRandomSeed{value: quote}(CALLBACK_GAS, GAS_PRICE, address(consumer), refundTo);
    }

    function testUnderpaidRequestRevertsAndExactQuoteSucceeds() public {
        uint256 quote = _quote();

        vm.prank(player);
        vm.expectRevert(MockRandooCoordinator.InsufficientFee.selector);
        consumer.roll{value: quote - 1}(CALLBACK_GAS, GAS_PRICE, refundTo);

        vm.prank(player);
        bytes32 reqHash = consumer.roll{value: quote}(CALLBACK_GAS, GAS_PRICE, refundTo);
        assertEq(consumer.lastReqHash(), reqHash);
    }

    // ------------------------------------------------------------------ fulfil

    function testFulfilDeliversSeedAndRejectsNonCoordinator() public {
        uint256 quote = _quote();
        vm.prank(player);
        bytes32 reqHash = consumer.roll{value: quote}(CALLBACK_GAS, GAS_PRICE, refundTo);

        // Nobody but the coordinator may deliver a seed.
        vm.prank(player);
        vm.expectRevert(RandooConsumerRonin.OnlyCoordinatorCanFulfill.selector);
        consumer.rawFulfillRandomSeed(reqHash, 1);
        assertEq(consumer.lastSeed(), 0, "seed must not land from a stranger");

        uint256 seed = uint256(keccak256("seed"));
        // Same 7-field event the live coordinator emits (requestId 1: first request).
        vm.expectEmit(true, true, false, true, address(coordinator));
        emit MockRandooCoordinator.RandomSeedFulfilled(reqHash, 1, seed, 0, 0, 0, true);
        bool ok = coordinator.fulfil(reqHash, seed);
        assertTrue(ok, "fulfil should succeed");
        assertEq(consumer.lastSeed(), seed, "consumer should store the seed");
        assertEq(consumer.lastReqHash(), reqHash);
    }

    /// @dev One-shot: the oracle fulfils exactly once and never redelivers.
    function testFulfilTwiceReverts() public {
        uint256 quote = _quote();
        vm.prank(player);
        bytes32 reqHash = consumer.roll{value: quote}(CALLBACK_GAS, GAS_PRICE, refundTo);

        uint256 seed = uint256(keccak256("seed"));
        assertTrue(coordinator.fulfil(reqHash, seed));
        assertTrue(coordinator.fulfilled(reqHash), "request must be marked fulfilled");

        vm.expectRevert(MockRandooCoordinator.AlreadyFulfilled.selector);
        coordinator.fulfil(reqHash, seed + 1);
        assertEq(consumer.lastSeed(), seed, "the first seed must stand");
    }

    function testFulfilAgainstRevertingConsumerReturnsFalse() public {
        RevertingConsumer bad = new RevertingConsumer(address(coordinator));
        uint256 quote = _quote();
        vm.prank(player);
        bytes32 reqHash = bad.roll{value: quote}(CALLBACK_GAS, GAS_PRICE, refundTo);

        bool ok = coordinator.fulfil(reqHash, 42);
        assertFalse(ok, "callback revert must surface as success == false, not a revert");

        // A failed callback is still consumed: no redelivery, the seed is not re-rolled.
        vm.expectRevert(MockRandooCoordinator.AlreadyFulfilled.selector);
        coordinator.fulfil(reqHash, 43);
    }
}

export SCRATCH="$(mktemp -d)" && cd "$SCRATCH" && forge init --no-git randoo-check && cd randoo-check

forge test -vv
cast call 0xC66eB2e7EE91145875000Ad46B55600000000001 "estimateRequestRandomFee(uint256,uint256)(uint256)" 250000 25000000000 --rpc-url https://saigon-testnet.roninchain.com/rpc

cast chain-id --rpc-url https://saigon-testnet.roninchain.com/rpc        # must print 202601
forge create src/<YourConsumer>.sol:<YourConsumer> --constructor-args 0xC66eB2e7EE91145875000Ad46B55600000000001 --rpc-url https://saigon-testnet.roninchain.com/rpc --account <alias> --broadcast
cast send <consumer> "roll(uint256,uint256,address)" 250000 25000000000 <refund-named-by-A2> --value <quote-wei> --rpc-url https://saigon-testnet.roninchain.com/rpc --account <alias>

# Randoo integration report
## Inventory            file:line | contract | base | binding | address + network
## Uses                 what each seed decides; state locked at request, resolved in the callback
## Changes              consumer (file, entry point, callbackGasLimit, gasPrice); refund address named by A2; files touched
## Unchanged            base + interface (verbatim); template assertions
## Verification         forge test, fee quote, minRequestGasPrice, cast implementation per network, date
## Human must re-verify deploy/env per environment; refund-address ownership; mainnet rollout
## Stops hit            unverified: implementation changed / wrong chain / address mismatch / network