Contract Source Code:
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.28;
import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
import {IEntropyConsumer} from "@pythnetwork/entropy-sdk-solidity/IEntropyConsumer.sol";
import {IEntropy} from "@pythnetwork/entropy-sdk-solidity/IEntropy.sol";
/// @title Pinata - A decentralized prize game using Pyth's entropy
/// @author Jean Ayala
/// @notice This contract implements a game where users can hit a pinata for prizes
/// @dev Uses Pyth Network's entropy for random number generation and implements reentrancy protection
contract Pinata is ReentrancyGuard, Ownable, IEntropyConsumer {
IEntropy private entropy;
// EVENTS
/// @notice Emitted when a user wins a regular prize
/// @param user Address of the winner
/// @param amount Prize amount won
event UserWonPrize(address user, uint256 amount);
/// @notice Emitted when a user breaks the pinata and wins the jackpot
/// @param user Address of the winner
/// @param amount Jackpot amount won
event UserWonJackpot(address user, uint256 amount);
/// @notice Emitted when a user attempts to hit the pinata
/// @param user Address of the player
/// @param pinata Address of this contract
/// @param sequenceNumber Unique identifier for this attempt
event UserTriesToHit(address user, address pinata, uint256 sequenceNumber);
/// @notice Emitted when the prize pool receives additional funds
/// @param user Address of the contributor
/// @param amount Amount added to the prize pool
event PrizePoolRefilled(address user, uint256 amount);
/// @notice Emitted when funds are withdrawn from the prize pool
/// @param user Address of the withdrawer
/// @param amount Amount withdrawn
event PrizePoolWithdrawed(address user, uint256 amount);
/// @notice Emitted with the result of a hit attempt
/// @param user Address of the player
/// @param entropyProvider Address of the entropy provider
/// @param sequenceNumber Unique identifier for this attempt
/// @param firstNumber First number in the sequence
/// @param secondNumber Second number in the sequence
/// @param thirdNumber Third number in the sequence
/// @param timesHit Total number of times the pinata has been hit
/// @param totalPayed Total amount paid out in prizes
event HitResult(
address user,
address entropyProvider,
uint256 sequenceNumber,
uint256 firstNumber,
uint256 secondNumber,
uint256 thirdNumber,
uint256 timesHit,
uint256 totalPayed
);
/// @notice Emitted when benefits are withdrawn
/// @param recipient Address receiving the benefits
/// @param amount Amount withdrawn
/// @param isCreator Whether the recipient is the creator or platform
event BenefitsWithdrawn(
address indexed recipient,
uint256 amount,
bool isCreator
);
/// @notice Emitted when the game state is reset
/// @param user Address that triggered the reset
/// @param sequenceNumber Sequence number at reset
/// @param timestamp Time of reset
event StateReset(address indexed user, uint256 sequenceNumber, uint256 timestamp);
/// @notice Emitted when fees are accumulated
/// @param creatorAmount Amount accumulated for creator
/// @param platformAmount Amount accumulated for platform
/// @param timestamp Time of accumulation
event FeesAccumulated(uint256 creatorAmount, uint256 platformAmount, uint256 timestamp);
// STATES
/// @notice Address of the entropy provider for random number generation
address private entropyProvider;
/// @notice Address that receives platform fees
address public platformAddress;
/// @notice Indicates if the pinata has been broken (jackpot won)
bool public pinataIsBroken = false;
/// @notice Indicates if the jackpot sequence has been initialized
bool public hasJackpotSequence;
/// @notice Indicates if winning sequences have been initialized
bool private sequencesInitialized;
/// @notice Maximum multiplier for prizes
uint256 public maxMultiplier;
/// @notice Total number of times the pinata has been hit
uint256 public hasBeenHit;
/// @notice Total amount paid out in prizes
uint256 public hasBeenPaid;
/// @notice Cost to hit the pinata once
uint256 public hitCost;
/// @notice Fee percentage for the creator (in basis points)
uint256 public creatorFee;
/// @notice Accumulated benefits for the creator
uint256 public creatorBenefits;
/// @notice Fee percentage for the platform (in basis points)
uint256 public platformFee;
/// @notice Accumulated benefits for the platform
uint256 public platformBenefits;
/// @notice Hash of the jackpot winning sequence
bytes32 public jackpotSequence;
/// @notice Maximum range for the second number in sequences
uint256 public secondNumberMaxRange;
/// @notice Initial prize pool amount
uint256 public originalPrizePool;
/// @notice Amount withdrawn by the owner
uint256 public ownerWithdrawn;
/// @notice Maximum total fees (15%)
uint256 public constant MAX_TOTAL_FEES = 15;
/// @notice Mapping of range index to allowed range values
mapping(uint8 => uint256) private allowedRanges;
/// @notice Mapping of player address to their current sequence number
mapping(address => uint256) public playerNumbers;
/// @notice Mapping of sequence number to player address
mapping(uint256 => address) private numberToPlayer;
/// @notice Mapping of sequence hash to prize amount
mapping(bytes32 => uint256) public winningSequences;
/// @notice Initializes the Pinata contract
/// @dev Sets up the initial state, prize pool, and winning sequences
/// @param _initialOwner Address of the contract owner
/// @param _prizePool Initial amount for the prize pool
/// @param _hitCost Cost to hit the pinata
/// @param _creatorFee Fee percentage for creator (in basis points)
/// @param _platformFee Fee percentage for platform (in basis points)
/// @param _platformAddress Address to receive platform fees
/// @param _entropyAddress Address of the entropy contract
/// @param _entropyProvider Address of the entropy provider
/// @param _rangeIndex Index for selecting the number range
constructor(
address _initialOwner,
uint256 _prizePool,
uint256 _hitCost,
uint256 _creatorFee,
uint256 _platformFee,
address _platformAddress,
address _entropyAddress,
address _entropyProvider,
uint8 _rangeIndex
) payable Ownable(_initialOwner) {
require(_initialOwner != address(0), "Invalid owner address");
require(_platformAddress != address(0), "Invalid platform address");
require(_entropyAddress != address(0), "Invalid entropy address");
require(_entropyProvider != address(0), "Invalid entropy provider");
require(_creatorFee <= 1000, "Fees cannot exceed 10%");
require(
(_creatorFee + _platformFee) <= MAX_TOTAL_FEES * 10000,
"Fees cant be more than 15%"
);
require(msg.value >= _prizePool, "Insufficient initial prize pool");
// Initialize allowed ranges
allowedRanges[0] = 6;
allowedRanges[1] = 8;
allowedRanges[2] = 12;
allowedRanges[3] = 18;
allowedRanges[4] = 24;
require(_rangeIndex <= 4, "Invalid range index");
secondNumberMaxRange = allowedRanges[_rangeIndex];
require(
_prizePool >= (_hitCost * (secondNumberMaxRange - 1)),
"Prize pool cant cover max prize"
);
maxMultiplier = secondNumberMaxRange - 1;
hitCost = _hitCost;
_initializeWinningSequences();
_initializeJackpotSequence();
creatorFee = _creatorFee;
platformFee = _platformFee;
platformAddress = _platformAddress;
originalPrizePool = _prizePool;
entropy = IEntropy(_entropyAddress);
entropyProvider = _entropyProvider;
}
// FUNCTIONS
// A function to try to hit the pinata
function hitPinata(bytes32 userRandomNumber) public payable nonReentrant {
require(!pinataIsBroken, "This pinata has been broken and the jackpot claimed");
uint256 _hitCost = hitCost; // Cache storage read
uint256 _maxMultiplier = maxMultiplier; // Cache storage read
uint256 fee = entropy.getFee(entropyProvider);
// Explicit overflow check for totalCost
require(_hitCost <= type(uint256).max - fee, "Cost overflow");
uint256 totalCost = _hitCost + fee;
// Explicit overflow check for maxPrize
require(_hitCost <= type(uint256).max / _maxMultiplier, "Prize calculation overflow");
uint256 maxPrize = _hitCost * _maxMultiplier;
require(playerNumbers[msg.sender] == 0, "user is already playing"); // this is 0 again once the user finish playing
require(msg.value >= totalCost, "no enought payment to hit the pinata");
require(
address(this).balance >=
maxPrize + creatorBenefits + platformBenefits,
"Insufficient contract balance for potential prizes"
);
// here we call entropy of pyth
uint64 sequenceNumber = entropy.requestWithCallback{value: fee}(
entropyProvider,
userRandomNumber
);
playerNumbers[msg.sender] = sequenceNumber;
numberToPlayer[sequenceNumber] = msg.sender; // this will be deleted once the user finish playing
// Calculate fees based on hitCost using basis points with precision loss protection
// First multiply all components to maintain precision
uint256 creatorAmount = (_hitCost * creatorFee);
uint256 platformAmount = (_hitCost * platformFee);
// Perform division last to minimize precision loss
creatorAmount = creatorAmount / 10000;
platformAmount = platformAmount / 10000;
// Explicit overflow checks for benefits accumulation
require(creatorBenefits <= type(uint256).max - creatorAmount, "Creator benefits overflow");
require(platformBenefits <= type(uint256).max - platformAmount, "Platform benefits overflow");
creatorBenefits += creatorAmount;
platformBenefits += platformAmount;
emit FeesAccumulated(creatorAmount, platformAmount, block.timestamp);
emit UserTriesToHit(msg.sender, address(this), sequenceNumber);
// Refund excess payment if user sent more than required
uint256 excess = msg.value - totalCost;
if (excess > 0) {
(bool success, ) = payable(msg.sender).call{value: excess}("");
require(success, "Refund transfer failed");
}
}
function entropyCallback(
uint64 sequenceNumber,
address provider,
bytes32 randomNumber
) internal override {
address user = numberToPlayer[sequenceNumber];
require(user != address(0), "Invalid user address");
hasBeenHit += 1;
uint256[3] memory sequence = generateSequence(
randomNumber,
secondNumberMaxRange
);
uint256 prize = getPrizeForSequence(sequence);
if (prize > 0) {
sendPrize(prize, user);
}
delete numberToPlayer[sequenceNumber];
playerNumbers[user] = 0;
emit HitResult(
user,
provider,
sequenceNumber,
sequence[0],
sequence[1],
sequence[2],
hasBeenHit,
hasBeenPaid
);
}
// Maps a random number into a range between minRange and maxRange (inclusive)
function mapRandomNumber(
bytes32 randomNumber,
uint256 minRange,
uint256 maxRange
) internal pure returns (uint256) {
uint256 range = maxRange - minRange + 1;
return minRange + (uint256(randomNumber) % range);
}
function generateSequence(
bytes32 randomNumber,
uint256 maxRange
) internal pure returns (uint256[3] memory) {
uint256 firstResult = mapRandomNumber(
keccak256(abi.encodePacked(randomNumber, "first")),
1,
maxRange
);
uint256 secondResult = mapRandomNumber(
keccak256(abi.encodePacked(randomNumber, "second")),
1,
maxRange
);
uint256 thirdResult = mapRandomNumber(
keccak256(abi.encodePacked(randomNumber, "third")),
1,
maxRange
);
uint256[3] memory sequence = [firstResult, secondResult, thirdResult];
return sequence;
}
// Function to withdraw accumulated benefits for either creator or platform
function withdrawBenefits(bool isCreator) public nonReentrant {
uint256 amount;
address recipient;
if (isCreator) {
require(
creatorBenefits > 0,
"No creator benefits available to withdraw"
);
amount = creatorBenefits;
creatorBenefits = 0;
recipient = owner();
} else {
require(
msg.sender == platformAddress,
"Only platform can withdraw platform benefits"
);
require(
platformBenefits > 0,
"No platform benefits available to withdraw"
);
amount = platformBenefits;
platformBenefits = 0;
recipient = platformAddress;
}
emit BenefitsWithdrawn(recipient, amount, isCreator);
(bool success, ) = payable(recipient).call{value: amount}("");
require(success, "Transfer failed");
}
function getEntropy() internal view override returns (address) {
return address(entropy);
}
// Function to get the prize amount for a given sequence
// This function also calculates the jackpot minus creator or platform benefits
function getPrizeForSequence(uint256[3] memory _sequence) public view returns (uint256) {
// Create sequence array directly without additional conversion
uint8[] memory sequence = new uint8[](3);
for(uint256 i = 0; i < 3; i++) {
require(_sequence[i] <= type(uint8).max, "Sequence number too large");
sequence[i] = uint8(_sequence[i]);
}
bytes32 keyHash = keccak256(abi.encodePacked(sequence));
if (hasJackpotSequence && keyHash == jackpotSequence) {
return address(this).balance - creatorBenefits - platformBenefits;
}
return winningSequences[keyHash];
}
// A function to send a prize, minus the creator and plaform benefits
function sendPrize(uint256 _amount, address _winner) internal {
require(_winner != address(0), "Invalid winner address");
require(_amount > 0, "Prize amount must be greater than 0");
require(
_amount <=
address(this).balance - creatorBenefits - platformBenefits,
"Insufficient contract balance"
);
// Calculate fees using basis points
uint256 creatorAmount = (_amount * creatorFee) / 10000;
uint256 platformAmount = (_amount * platformFee) / 10000;
uint256 finalPrizeAmount = _amount - creatorAmount - platformAmount;
// Check if this is a jackpot win
bool isJackpot = finalPrizeAmount ==
address(this).balance - creatorBenefits - platformBenefits;
// Update state before transfer
creatorBenefits += creatorAmount;
platformBenefits += platformAmount;
hasBeenPaid += finalPrizeAmount;
if (isJackpot) {
pinataIsBroken = true;
emit UserWonJackpot(_winner, finalPrizeAmount);
} else {
emit UserWonPrize(_winner, finalPrizeAmount);
}
// Send prize to user
(bool success, ) = payable(_winner).call{value: finalPrizeAmount}("");
require(success, "Prize transfer failed");
}
function _initializeWinningSequences() private {
require(!sequencesInitialized, "Sequences already initialized");
// Initialize full sequences (all three numbers match)
for (uint8 i = 1; i < secondNumberMaxRange; i++) {
uint8[] memory sequence = new uint8[](3);
sequence[0] = i;
sequence[1] = i;
sequence[2] = i;
bytes32 keyHash = keccak256(abi.encodePacked(sequence));
winningSequences[keyHash] = i * hitCost;
}
// Initialize partial sequences (two numbers match)
for (uint8 i = 1; i < secondNumberMaxRange; i++) {
require(hitCost <= type(uint256).max / i, "Prize calculation overflow");
for (uint8 j = 1; j <= secondNumberMaxRange; j++) {
if (i != j) {
// Pattern: [i,i,j] - Prize is hitCost * (i/2)
uint8[] memory seq1 = new uint8[](3);
seq1[0] = i;
seq1[1] = i;
seq1[2] = j;
bytes32 keyHash1 = keccak256(abi.encodePacked(seq1));
winningSequences[keyHash1] = (hitCost * i) / 2; // Changed order of operations
// Pattern: [j,i,i] - Prize is hitCost * (i/2)
uint8[] memory seq3 = new uint8[](3);
seq3[0] = j;
seq3[1] = i;
seq3[2] = i;
bytes32 keyHash3 = keccak256(abi.encodePacked(seq3));
winningSequences[keyHash3] = (hitCost * i) / 2; // Changed order of operations
}
}
}
sequencesInitialized = true;
}
function _initializeJackpotSequence() private {
require(!hasJackpotSequence, "Jackpot sequence already initialized");
uint8[] memory sequence = new uint8[](3);
sequence[0] = uint8(secondNumberMaxRange);
sequence[1] = uint8(secondNumberMaxRange);
sequence[2] = uint8(secondNumberMaxRange);
jackpotSequence = keccak256(abi.encodePacked(sequence));
hasJackpotSequence = true;
}
// Function to refill the prize pool
function refillPrizePool() public payable nonReentrant {
require(msg.value > 0, "Must send some ETH to refill");
require(!pinataIsBroken, "Cannot refill a broken pinata");
emit PrizePoolRefilled(msg.sender, msg.value);
}
function withdrawPrizePool() external onlyOwner nonReentrant {
require(!pinataIsBroken, "Cannot withdraw from broken pinata");
require(
address(this).balance > creatorBenefits + platformBenefits,
"No funds available for withdrawal"
);
uint256 availableForWithdrawal = originalPrizePool - ownerWithdrawn;
require(availableForWithdrawal > 0, "No prize pool left to withdraw");
uint256 actualBalance = address(this).balance -
creatorBenefits -
platformBenefits;
uint256 withdrawAmount = availableForWithdrawal;
if (actualBalance < withdrawAmount) {
withdrawAmount = actualBalance;
}
// Calculate required balance for max prize
uint256 maxPrize = hitCost * maxMultiplier;
require(
(actualBalance - withdrawAmount) >= maxPrize,
"Withdrawal would leave insufficient funds for max prize"
);
ownerWithdrawn += withdrawAmount;
(bool success, ) = payable(owner()).call{value: withdrawAmount}("");
require(success, "Transfer failed");
}
}
// SPDX-License-Identifier: Apache 2
pragma solidity ^0.8.0;
abstract contract IEntropyConsumer {
// This method is called by Entropy to provide the random number to the consumer.
// It asserts that the msg.sender is the Entropy contract. It is not meant to be
// override by the consumer.
function _entropyCallback(
uint64 sequence,
address provider,
bytes32 randomNumber
) external {
address entropy = getEntropy();
require(entropy != address(0), "Entropy address not set");
require(msg.sender == entropy, "Only Entropy can call this function");
entropyCallback(sequence, provider, randomNumber);
}
// getEntropy returns Entropy contract address. The method is being used to check that the
// callback is indeed from Entropy contract. The consumer is expected to implement this method.
// Entropy address can be found here - https://docs.pyth.network/entropy/contract-addresses
function getEntropy() internal view virtual returns (address);
// This method is expected to be implemented by the consumer to handle the random number.
// It will be called by _entropyCallback after _entropyCallback ensures that the call is
// indeed from Entropy contract.
function entropyCallback(
uint64 sequence,
address provider,
bytes32 randomNumber
) internal virtual;
}
// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.0) (access/Ownable.sol)
pragma solidity ^0.8.20;
import {Context} from "../utils/Context.sol";
/**
* @dev Contract module which provides a basic access control mechanism, where
* there is an account (an owner) that can be granted exclusive access to
* specific functions.
*
* The initial owner is set to the address provided by the deployer. This can
* later be changed with {transferOwnership}.
*
* This module is used through inheritance. It will make available the modifier
* `onlyOwner`, which can be applied to your functions to restrict their use to
* the owner.
*/
abstract contract Ownable is Context {
address private _owner;
/**
* @dev The caller account is not authorized to perform an operation.
*/
error OwnableUnauthorizedAccount(address account);
/**
* @dev The owner is not a valid owner account. (eg. `address(0)`)
*/
error OwnableInvalidOwner(address owner);
event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
/**
* @dev Initializes the contract setting the address provided by the deployer as the initial owner.
*/
constructor(address initialOwner) {
if (initialOwner == address(0)) {
revert OwnableInvalidOwner(address(0));
}
_transferOwnership(initialOwner);
}
/**
* @dev Throws if called by any account other than the owner.
*/
modifier onlyOwner() {
_checkOwner();
_;
}
/**
* @dev Returns the address of the current owner.
*/
function owner() public view virtual returns (address) {
return _owner;
}
/**
* @dev Throws if the sender is not the owner.
*/
function _checkOwner() internal view virtual {
if (owner() != _msgSender()) {
revert OwnableUnauthorizedAccount(_msgSender());
}
}
/**
* @dev Leaves the contract without owner. It will not be possible to call
* `onlyOwner` functions. Can only be called by the current owner.
*
* NOTE: Renouncing ownership will leave the contract without an owner,
* thereby disabling any functionality that is only available to the owner.
*/
function renounceOwnership() public virtual onlyOwner {
_transferOwnership(address(0));
}
/**
* @dev Transfers ownership of the contract to a new account (`newOwner`).
* Can only be called by the current owner.
*/
function transferOwnership(address newOwner) public virtual onlyOwner {
if (newOwner == address(0)) {
revert OwnableInvalidOwner(address(0));
}
_transferOwnership(newOwner);
}
/**
* @dev Transfers ownership of the contract to a new account (`newOwner`).
* Internal function without access restriction.
*/
function _transferOwnership(address newOwner) internal virtual {
address oldOwner = _owner;
_owner = newOwner;
emit OwnershipTransferred(oldOwner, newOwner);
}
}
// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.1.0) (utils/ReentrancyGuard.sol)
pragma solidity ^0.8.20;
/**
* @dev Contract module that helps prevent reentrant calls to a function.
*
* Inheriting from `ReentrancyGuard` will make the {nonReentrant} modifier
* available, which can be applied to functions to make sure there are no nested
* (reentrant) calls to them.
*
* Note that because there is a single `nonReentrant` guard, functions marked as
* `nonReentrant` may not call one another. This can be worked around by making
* those functions `private`, and then adding `external` `nonReentrant` entry
* points to them.
*
* TIP: If EIP-1153 (transient storage) is available on the chain you're deploying at,
* consider using {ReentrancyGuardTransient} instead.
*
* TIP: If you would like to learn more about reentrancy and alternative ways
* to protect against it, check out our blog post
* https://blog.openzeppelin.com/reentrancy-after-istanbul/[Reentrancy After Istanbul].
*/
abstract contract ReentrancyGuard {
// Booleans are more expensive than uint256 or any type that takes up a full
// word because each write operation emits an extra SLOAD to first read the
// slot's contents, replace the bits taken up by the boolean, and then write
// back. This is the compiler's defense against contract upgrades and
// pointer aliasing, and it cannot be disabled.
// The values being non-zero value makes deployment a bit more expensive,
// but in exchange the refund on every call to nonReentrant will be lower in
// amount. Since refunds are capped to a percentage of the total
// transaction's gas, it is best to keep them low in cases like this one, to
// increase the likelihood of the full refund coming into effect.
uint256 private constant NOT_ENTERED = 1;
uint256 private constant ENTERED = 2;
uint256 private _status;
/**
* @dev Unauthorized reentrant call.
*/
error ReentrancyGuardReentrantCall();
constructor() {
_status = NOT_ENTERED;
}
/**
* @dev Prevents a contract from calling itself, directly or indirectly.
* Calling a `nonReentrant` function from another `nonReentrant`
* function is not supported. It is possible to prevent this from happening
* by making the `nonReentrant` function external, and making it call a
* `private` function that does the actual work.
*/
modifier nonReentrant() {
_nonReentrantBefore();
_;
_nonReentrantAfter();
}
function _nonReentrantBefore() private {
// On the first call to nonReentrant, _status will be NOT_ENTERED
if (_status == ENTERED) {
revert ReentrancyGuardReentrantCall();
}
// Any calls to nonReentrant after this point will fail
_status = ENTERED;
}
function _nonReentrantAfter() private {
// By storing the original value once again, a refund is triggered (see
// https://eips.ethereum.org/EIPS/eip-2200)
_status = NOT_ENTERED;
}
/**
* @dev Returns true if the reentrancy guard is currently set to "entered", which indicates there is a
* `nonReentrant` function in the call stack.
*/
function _reentrancyGuardEntered() internal view returns (bool) {
return _status == ENTERED;
}
}
// SPDX-License-Identifier: Apache 2
pragma solidity ^0.8.0;
import "./EntropyEvents.sol";
interface IEntropy is EntropyEvents {
// Register msg.sender as a randomness provider. The arguments are the provider's configuration parameters
// and initial commitment. Re-registering the same provider rotates the provider's commitment (and updates
// the feeInWei).
//
// chainLength is the number of values in the hash chain *including* the commitment, that is, chainLength >= 1.
function register(
uint128 feeInWei,
bytes32 commitment,
bytes calldata commitmentMetadata,
uint64 chainLength,
bytes calldata uri
) external;
// Withdraw a portion of the accumulated fees for the provider msg.sender.
// Calling this function will transfer `amount` wei to the caller (provided that they have accrued a sufficient
// balance of fees in the contract).
function withdraw(uint128 amount) external;
// Withdraw a portion of the accumulated fees for provider. The msg.sender must be the fee manager for this provider.
// Calling this function will transfer `amount` wei to the caller (provided that they have accrued a sufficient
// balance of fees in the contract).
function withdrawAsFeeManager(address provider, uint128 amount) external;
// As a user, request a random number from `provider`. Prior to calling this method, the user should
// generate a random number x and keep it secret. The user should then compute hash(x) and pass that
// as the userCommitment argument. (You may call the constructUserCommitment method to compute the hash.)
//
// This method returns a sequence number. The user should pass this sequence number to
// their chosen provider (the exact method for doing so will depend on the provider) to retrieve the provider's
// number. The user should then call fulfillRequest to construct the final random number.
//
// This method will revert unless the caller provides a sufficient fee (at least getFee(provider)) as msg.value.
// Note that excess value is *not* refunded to the caller.
function request(
address provider,
bytes32 userCommitment,
bool useBlockHash
) external payable returns (uint64 assignedSequenceNumber);
// Request a random number. The method expects the provider address and a secret random number
// in the arguments. It returns a sequence number.
//
// The address calling this function should be a contract that inherits from the IEntropyConsumer interface.
// The `entropyCallback` method on that interface will receive a callback with the generated random number.
//
// This method will revert unless the caller provides a sufficient fee (at least getFee(provider)) as msg.value.
// Note that excess value is *not* refunded to the caller.
function requestWithCallback(
address provider,
bytes32 userRandomNumber
) external payable returns (uint64 assignedSequenceNumber);
// Fulfill a request for a random number. This method validates the provided userRandomness and provider's proof
// against the corresponding commitments in the in-flight request. If both values are validated, this function returns
// the corresponding random number.
//
// Note that this function can only be called once per in-flight request. Calling this function deletes the stored
// request information (so that the contract doesn't use a linear amount of storage in the number of requests).
// If you need to use the returned random number more than once, you are responsible for storing it.
function reveal(
address provider,
uint64 sequenceNumber,
bytes32 userRevelation,
bytes32 providerRevelation
) external returns (bytes32 randomNumber);
// Fulfill a request for a random number. This method validates the provided userRandomness
// and provider's revelation against the corresponding commitment in the in-flight request. If both values are validated
// and the requestor address is a contract address, this function calls the requester's entropyCallback method with the
// sequence number, provider address and the random number as arguments. Else if the requestor is an EOA, it won't call it.
//
// Note that this function can only be called once per in-flight request. Calling this function deletes the stored
// request information (so that the contract doesn't use a linear amount of storage in the number of requests).
// If you need to use the returned random number more than once, you are responsible for storing it.
//
// Anyone can call this method to fulfill a request, but the callback will only be made to the original requester.
function revealWithCallback(
address provider,
uint64 sequenceNumber,
bytes32 userRandomNumber,
bytes32 providerRevelation
) external;
function getProviderInfo(
address provider
) external view returns (EntropyStructs.ProviderInfo memory info);
function getDefaultProvider() external view returns (address provider);
function getRequest(
address provider,
uint64 sequenceNumber
) external view returns (EntropyStructs.Request memory req);
function getFee(address provider) external view returns (uint128 feeAmount);
function getAccruedPythFees()
external
view
returns (uint128 accruedPythFeesInWei);
function setProviderFee(uint128 newFeeInWei) external;
function setProviderFeeAsFeeManager(
address provider,
uint128 newFeeInWei
) external;
function setProviderUri(bytes calldata newUri) external;
// Set manager as the fee manager for the provider msg.sender.
// After calling this function, manager will be able to set the provider's fees and withdraw them.
// Only one address can be the fee manager for a provider at a time -- calling this function again with a new value
// will override the previous value. Call this function with the all-zero address to disable the fee manager role.
function setFeeManager(address manager) external;
function constructUserCommitment(
bytes32 userRandomness
) external pure returns (bytes32 userCommitment);
function combineRandomValues(
bytes32 userRandomness,
bytes32 providerRandomness,
bytes32 blockHash
) external pure returns (bytes32 combinedRandomness);
}
// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.0.1) (utils/Context.sol)
pragma solidity ^0.8.20;
/**
* @dev Provides information about the current execution context, including the
* sender of the transaction and its data. While these are generally available
* via msg.sender and msg.data, they should not be accessed in such a direct
* manner, since when dealing with meta-transactions the account sending and
* paying for execution may not be the actual sender (as far as an application
* is concerned).
*
* This contract is only required for intermediate, library-like contracts.
*/
abstract contract Context {
function _msgSender() internal view virtual returns (address) {
return msg.sender;
}
function _msgData() internal view virtual returns (bytes calldata) {
return msg.data;
}
function _contextSuffixLength() internal view virtual returns (uint256) {
return 0;
}
}
// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.8.0;
import "./EntropyStructs.sol";
interface EntropyEvents {
event Registered(EntropyStructs.ProviderInfo provider);
event Requested(EntropyStructs.Request request);
event RequestedWithCallback(
address indexed provider,
address indexed requestor,
uint64 indexed sequenceNumber,
bytes32 userRandomNumber,
EntropyStructs.Request request
);
event Revealed(
EntropyStructs.Request request,
bytes32 userRevelation,
bytes32 providerRevelation,
bytes32 blockHash,
bytes32 randomNumber
);
event RevealedWithCallback(
EntropyStructs.Request request,
bytes32 userRandomNumber,
bytes32 providerRevelation,
bytes32 randomNumber
);
event ProviderFeeUpdated(address provider, uint128 oldFee, uint128 newFee);
event ProviderUriUpdated(address provider, bytes oldUri, bytes newUri);
event ProviderFeeManagerUpdated(
address provider,
address oldFeeManager,
address newFeeManager
);
event Withdrawal(
address provider,
address recipient,
uint128 withdrawnAmount
);
}
// SPDX-License-Identifier: Apache 2
pragma solidity ^0.8.0;
contract EntropyStructs {
struct ProviderInfo {
uint128 feeInWei;
uint128 accruedFeesInWei;
// The commitment that the provider posted to the blockchain, and the sequence number
// where they committed to this. This value is not advanced after the provider commits,
// and instead is stored to help providers track where they are in the hash chain.
bytes32 originalCommitment;
uint64 originalCommitmentSequenceNumber;
// Metadata for the current commitment. Providers may optionally use this field to help
// manage rotations (i.e., to pick the sequence number from the correct hash chain).
bytes commitmentMetadata;
// Optional URI where clients can retrieve revelations for the provider.
// Client SDKs can use this field to automatically determine how to retrieve random values for each provider.
// TODO: specify the API that must be implemented at this URI
bytes uri;
// The first sequence number that is *not* included in the current commitment (i.e., an exclusive end index).
// The contract maintains the invariant that sequenceNumber <= endSequenceNumber.
// If sequenceNumber == endSequenceNumber, the provider must rotate their commitment to add additional random values.
uint64 endSequenceNumber;
// The sequence number that will be assigned to the next inbound user request.
uint64 sequenceNumber;
// The current commitment represents an index/value in the provider's hash chain.
// These values are used to verify requests for future sequence numbers. Note that
// currentCommitmentSequenceNumber < sequenceNumber.
//
// The currentCommitment advances forward through the provider's hash chain as values
// are revealed on-chain.
bytes32 currentCommitment;
uint64 currentCommitmentSequenceNumber;
// An address that is authorized to set / withdraw fees on behalf of this provider.
address feeManager;
}
struct Request {
// Storage slot 1 //
address provider;
uint64 sequenceNumber;
// The number of hashes required to verify the provider revelation.
uint32 numHashes;
// Storage slot 2 //
// The commitment is keccak256(userCommitment, providerCommitment). Storing the hash instead of both saves 20k gas by
// eliminating 1 store.
bytes32 commitment;
// Storage slot 3 //
// The number of the block where this request was created.
// Note that we're using a uint64 such that we have an additional space for an address and other fields in
// this storage slot. Although block.number returns a uint256, 64 bits should be plenty to index all of the
// blocks ever generated.
uint64 blockNumber;
// The address that requested this random number.
address requester;
// If true, incorporate the blockhash of blockNumber into the generated random value.
bool useBlockhash;
// If true, the requester will be called back with the generated random value.
bool isRequestWithCallback;
// There are 2 remaining bytes of free space in this slot.
}
}