Skip to main content

DrawManager

Git Source

Author: G9 Software Inc.

The DrawManager contract is a permissionless RNG incentive layer for a Prize Pool.

State Variables

prizePool

================= Variables =================

The prize pool that this DrawManager is bound to

This contract should be the draw manager of the prize pool.

PrizePool public immutable prizePool;

rng

The random number generator that this DrawManager uses to generate random numbers

IRng public immutable rng;

auctionDuration

Duration of the auction in seconds

uint48 public immutable auctionDuration;

auctionTargetTime

The target duration of the auctions (elapsed time at close of auction)

uint48 public immutable auctionTargetTime;

_auctionTargetTimeFraction

The target time to complete the auction as a fraction of the auction duration

This just saves some calculations and is a duplicate of auctionTargetTime

UD2x18 internal immutable _auctionTargetTimeFraction;

maxRewards

The maximum total rewards for both auctions for a single draw

uint256 public immutable maxRewards;

maxRetries

The maximum number of times a start RNG request can be retried on failure.

uint256 public immutable maxRetries;

vaultBeneficiary

The address of a vault to contribute remaining reserve on behalf of

address public immutable vaultBeneficiary;

_startDrawAuctions

A stack of the last Start Draw Auction results

StartDrawAuction[] internal _startDrawAuctions;

lastStartDrawFraction

The last reward fraction used for the start rng auction

UD2x18 public lastStartDrawFraction;

lastFinishDrawFraction

The last reward fraction used for the finish draw auction

UD2x18 public lastFinishDrawFraction;

Functions

constructor

================= Constructor =================

Deploy the RngAuction smart contract.

constructor(
PrizePool _prizePool,
IRng _rng,
uint48 _auctionDuration,
uint48 _auctionTargetTime,
UD2x18 _firstStartDrawTargetFraction,
UD2x18 _firstFinishDrawTargetFraction,
uint256 _maxRewards,
uint256 _maxRetries,
address _vaultBeneficiary
);

Parameters

NameTypeDescription
_prizePoolPrizePoolAddress of the Prize Pool
_rngIRngAddress of the RNG service
_auctionDurationuint48Auction duration in seconds
_auctionTargetTimeuint48Target time to complete the auction in seconds
_firstStartDrawTargetFractionUD2x18The expected reward fraction for the first start rng auction (to help fine-tune the system)
_firstFinishDrawTargetFractionUD2x18The expected reward fraction for the first finish draw auction (to help fine-tune the system)
_maxRewardsuint256The maximum amount of rewards that can be allocated to the auction
_maxRetriesuint256The maximum number of times a start RNG request can be retried on failure.
_vaultBeneficiaryaddressThe address of a vault to contribute remaining reserve on behalf of

startDraw

================= External =================

Completes the start draw auction.

Will revert if recipient is zero, the draw id to award has not closed, the prize pool is shutdown, the start draw was already called for this draw, or if the rng is invalid.

function startDraw(address _rewardRecipient, uint32 _rngRequestId) external returns (uint24);

Parameters

NameTypeDescription
_rewardRecipientaddressAddress that will be allocated the reward for starting the RNG request. This reward can be withdrawn from the Prize Pool after it is successfully awarded.
_rngRequestIduint32The RNG request ID to use for randomness. This request must be made in the same block as this call.

Returns

NameTypeDescription
<none>uint24The draw id for which start draw was called.

canStartDraw

Checks if the start draw can be called.

function canStartDraw() public view returns (bool);

Returns

NameTypeDescription
<none>boolTrue if start draw can be called, false otherwise

startDrawReward

Calculates the current reward for starting the draw. If start draw cannot be called, this will be zero.

function startDrawReward() public view returns (uint256);

Returns

NameTypeDescription
<none>uint256The current reward denominated in prize tokens of the target prize pool.

finishDraw

Called to award the prize pool and pay out rewards.

function finishDraw(address _rewardRecipient) external returns (uint24);

Parameters

NameTypeDescription
_rewardRecipientaddressThe recipient of the finish draw reward.

Returns

NameTypeDescription
<none>uint24The awarded draw ID

canFinishDraw

Determines whether finish draw can be called.

function canFinishDraw() public view returns (bool);

Returns

NameTypeDescription
<none>boolTrue if the finish draw can be called, false otherwise.

finishDrawReward

Calculates the reward for calling finishDraw.

function finishDrawReward() public view returns (uint256 reward);

Returns

NameTypeDescription
rewarduint256The current reward denominated in prize tokens

getLastStartDrawAuction

================= State =================

The last auction results.

function getLastStartDrawAuction() public view returns (StartDrawAuction memory result);

Returns

NameTypeDescription
resultStartDrawAuctionStartDrawAuctions struct from the last auction.

getStartDrawAuctionCount

Returns the number of start draw auctions.

function getStartDrawAuctionCount() external view returns (uint256);

Returns

NameTypeDescription
<none>uint256The number of start draw auctions.

getStartDrawAuction

Returns the start draw auction at the given index.

function getStartDrawAuction(uint256 _index) external view returns (StartDrawAuction memory);

Parameters

NameTypeDescription
_indexuint256The index of the start draw auction to return.

Returns

NameTypeDescription
<none>StartDrawAuctionThe start draw auction at the given index.

_computeFinishDrawReward

Computes what the reward and reward fraction would be for the finish draw

Caps the reward such that the total rewards cannot exceed the available rewards

function _computeFinishDrawReward(
uint256 _auctionOpenedAt,
uint256 _auctionClosedAt,
uint256 _availableRewards,
UD2x18 _fractionalRewardsLeft
) internal view returns (uint256 reward, UD2x18 fraction);

Parameters

NameTypeDescription
_auctionOpenedAtuint256The time at which the auction started
_auctionClosedAtuint256The time at which the auction closed
_availableRewardsuint256The amount of rewards available
_fractionalRewardsLeftUD2x18The fraction of rewards that is available

Returns

NameTypeDescription
rewarduint256The reward for the finish draw auction
fractionUD2x18The reward fraction for the finish draw auction

_computeStartDrawRewards

Computes the rewards and reward fractions for the start draw auctions

Caps the reward such that the total rewards cannot exceed the available rewards

function _computeStartDrawRewards(uint256 _firstAuctionOpenedAt, uint256 _availableRewards)
internal
view
returns (uint256[] memory rewards, UD2x18[] memory fractions, UD2x18 totalRewardFractionLeft);

Parameters

NameTypeDescription
_firstAuctionOpenedAtuint256The time at which the first auction started
_availableRewardsuint256The amount of rewards available

Returns

NameTypeDescription
rewardsuint256[]The rewards for the start draw auctions
fractionsUD2x18[]The reward fractions for the start draw auctions
totalRewardFractionLeftUD2x18The total fractional rewards left [0.0, 1.0] range

_computeStartDrawReward

Computes the reward and reward fraction for the start draw auction

Caps the reward such that it cannot exceed the remaining amount

function _computeStartDrawReward(
uint256 _auctionOpenedAt,
uint256 _auctionClosedAt,
uint256 _availableRewards,
UD2x18 _fractionalRewardsLeft
) internal view returns (uint256 reward, UD2x18 fraction);

Parameters

NameTypeDescription
_auctionOpenedAtuint256The time at which the auction started
_auctionClosedAtuint256The time at which the auction closed
_availableRewardsuint256The amount of rewards available
_fractionalRewardsLeftUD2x18The fraction of rewards that is available

Returns

NameTypeDescription
rewarduint256The reward for the start draw auction
fractionUD2x18The reward fraction for the start draw auction

_isAuctionExpired

================= Internal =================

Checks if the auction has expired.

function _isAuctionExpired(uint256 closedAt) internal view returns (bool);

Parameters

NameTypeDescription
closedAtuint256The time at which the auction started

Returns

NameTypeDescription
<none>boolTrue if the auction has expired, false otherwise

_reward

Allocates the reward to the recipient.

function _reward(address _recipient, uint256 _amount) internal;

Parameters

NameTypeDescription
_recipientaddressThe recipient of the reward
_amountuint256The amount of the reward

_computeAvailableRewards

Computes the available rewards for the auction (limited by max).

function _computeAvailableRewards() internal view returns (uint256);

Returns

NameTypeDescription
<none>uint256The amount of rewards available for the auction

_computeElapsedTime

Calculates the elapsed time for the current RNG auction.

function _computeElapsedTime(uint256 _startTimestamp, uint256 _endTimestamp) internal pure returns (uint48);

Returns

NameTypeDescription
<none>uint48The elapsed time since the start of the current RNG auction in seconds.

Events

DrawStarted

================= Events =================

Emitted when start draw is called.

event DrawStarted(
address indexed sender,
address indexed recipient,
uint24 indexed drawId,
uint48 elapsedTime,
uint256 reward,
uint32 rngRequestId,
uint64 count
);

Parameters

NameTypeDescription
senderaddressThe address that triggered the rng auction
recipientaddressThe recipient of the auction reward
drawIduint24The draw id that this request is for
elapsedTimeuint48The amount of time that had elapsed when start draw was called
rewarduint256The reward for the start draw auction
rngRequestIduint32The RNGInterface request ID
countuint64The number of start draw auctions, including this one.

DrawFinished

Emitted when the finish draw is called

event DrawFinished(
address indexed sender,
address indexed recipient,
uint24 indexed drawId,
uint48 elapsedTime,
uint256 reward,
uint256 contribution
);

Parameters

NameTypeDescription
senderaddressThe address that triggered the finish draw auction
recipientaddressThe recipient of the finish draw auction reward
drawIduint24The draw id
elapsedTimeuint48The amount of time that had elapsed between start draw and finish draw
rewarduint256The reward for the finish draw auction
contributionuint256The amount of tokens contributed to the prize pool on behalf of the vault beneficiary

Structs

StartDrawAuction

A struct that stores the details of a Start Draw auction

struct StartDrawAuction {
address recipient;
uint40 closedAt;
uint24 drawId;
uint32 rngRequestId;
}

Properties

NameTypeDescription
recipientaddressThe recipient of the reward
closedAtuint40The time at which the auction closed
drawIduint24The draw id that the auction started
rngRequestIduint32The id of the RNG request that was made