Skip to content

Handling the callback ​

solidity
function fulfillRandomWords(uint256 requestId, uint256[] memory randomWords) internal override {
    // map requestId -> what it was for, use the words, emit an event
}

Rules ​

  1. Never revert. A reverting callback is recorded as a failed fulfilment and will not be retried. The request is final and you have still paid for it. Validate inputs at request time, not here.
  2. Stay well within callbackGasLimit. Running out of gas counts as a revert.
  3. Keep it small. Store the word (or a few derived values) and compute anything heavy in view functions. Writing large arrays inside the callback is the most common way to run out of gas. See Tournament seeding.
  4. Look up by requestId. Several requests can be in flight; never assume the callback answers your most recent one.
  5. Ignore unexpected ids. After a refund or a state change, a late answer for an old request should be a no-op, not a revert.
  6. Don't call untrusted contracts or send value from the callback. Record who won and let them withdraw (pull payments).

Only the coordinator can call you ​

rawFulfillRandomWords is the entry point. It checks msg.sender == s_coordinator and then calls your fulfillRandomWords. Don't override rawFulfillRandomWords.

Switching coordinators ​

The consumer's owner can call setCoordinator(newCoordinator), for example when Verity ships a new coordinator version. Requests still pending on the old coordinator will then fail their callback, so switch when nothing is pending.

Using several words ​

solidity
uint256 w = randomWords[0];
uint8 a = uint8(uint64(w) % 6);          // bits   0..63
uint8 b = uint8(uint64(w >> 64) % 6);    // bits  64..127: independent of a
uint256 c = uint256(keccak256(abi.encode(w, 2))) % 1000; // or derive more

Use disjoint bit ranges or hash derivations. Taking w % 100 and then (w >> 64) % 8 from the same word makes the two values correlated, because both depend on the same bits.

Testnet: PulseChain testnet v4. Unaudited software; do not use on mainnet yet.