Function Description of Lottery Contract

1. Function Description of Lottery Contract of Turntable Model

Contract item address github

1.1 Functions

  • Add contract owner and delete administrator
  • Administrator role create lottery and set lottery rules
  • Administrator role add prize and set prizewinning probability
  • Administrator role run and close lottery
  • Users draw lottery
  • Inquire lottery information according to lottery id
  • Inquire prize and prizewinning information according to lottery id and prize id

1.2 Lottery Contract Structure

  • LotteryData contract: Lottery data contract records the new lottery drawing, prize, probability and prizewinning information. The revision of all the data can only be carried out by external logic contract.
  • LotteryCore contract: Operable lottery data contract. admin role can be added. Only admin role can execute lottery drawing method of logic contract. owner role manages admin role.
  • LotteryCoreWithRule: Lottery logic contract with various rule restrictions. Based on LotteryCore, it adds various rule restrictions. The developer can have user-defined revision. For detailed rules, refer to the notes of data structure in the contract.

Data logic structures are separate, base data structure is fixed, and external logic update does not affect data contract.

1.3 Contract Deployment Process

  1. owner address is used as initial parameter to deploy LotteryData contract
  2. owner address and LotteryData are used as the parameters to deploy LotteryCoreWithRule contract (constructed function will set msg.sender as admin).
  3. Call LotteryData.setLotteryCore method, and the parameter is LotteryCoreWithRule address. Set the logic contract address of executable data contract

1.4 Operation Steps of LotteryCoreWithRule Logic Contract Function

  1. In the deployment of LotteryCoreWithRule contract, owner has been set as admin role.
  2. Use the account of admin role to callLotteryCoreWithRule.createLottery to create lottery. The parameters are lotteryName and other rule parameters. lotteryId is returned
  3. Use the account of admin role to call LotteryCoreWithRule.addLotteryPrize to add new lottery prizes to lotteryId. The parameters are prize name, prize number and prizewinning probabilityreciprocal
  4. Repeat Step 3 till the prize setting is completed
  5. Use the account of admin role to call LotteryCoreWithRule.startLottery to start the lottery with the id of lotteryId
  6. The user calls LotteryCoreWithRule.userDraw to participate in the lottery till lottery sends ending conditions (prizes all given or admin role account closes lottery)
  7. Inquire LotteryData.getLotteryPrizeInfo prize and user prizewinning information

1.5 Operation Steps of LotteryData Data Contract Function

  1. Inquire lottery information LotteryData.getLotteryInfo(_lotteryId) according to lottery id
  2. Inquire prize and prizewinning user information LotteryData.getLotteryPrizeInfo(_lotteryId, prizeIndex) according to lottery id
  3. Inquire lottery status LotteryData.getLotteryStatus(_lotteryId) according to lottery id
  4. Get lotteries array length LotteryData.getLotteriesLength()
  5. Get array length of lotery prize LotteryData.getLotteryPrizesLength()

1.6 Cautions of LotteryCoreWithRule Contract

  • When creating new contract, the parameters for input were owner address and lotteryData address
  • When creating new lottery, the starting time and ending time of lottery are time stamps. The input of the parameters daily lottery starting time and daily lottery ending time is integer value of hourly number (i.e. Input 8 for 8:00)
  • The daily lottery starting and ending time is restricted to time zone UTC(+8). Please change the parameter by yourself for other time zones

1.7 LotteryCoreWithRule User-Defined Rules

struct LotteryRule {     
  uint startTime;         // Lottery starting time stamp
  uint endTime;           // Lottery ending time stamp
  uint daysStartTime;     // Daily lottery starting time. 0 for no limit
  uint daysEndTime;       // Daily lottery ending time. 0 for no limit
  uint participateCnt;    // Lottery drawing times limit. 0 for no limit
  uint perAddressPartCnt; // Drawing times of each address. 0 for no limit
}

The parameters of new lottery can be user-defined lottery rules according to the needs

1.8 Core Realization

  1. Calculate prizewinning array When the administrator runs the lottery, the lowest common multiple of prizewinning probability reciprocal for all the prizes in the lottery is calculated in contract method, and then divided by prizewinning probability of each prize. The prizewinning arrant of each prize is obtained.
    For example:
    Prize Information and Lottery Array of the Lottery TestLottery

| Prize Name | Prizewinning Probability | Prizewinning Array | -------- | -------- | -------- | --------------- | | Prize A | 1% | 100 | [0] | | Prize B | 2% | 50 | [1, 2] | | Prize C | 5% | 20 | [3, 4, 5, 6, 7] |

As above: The lowest common multiple of prizewinning probability reciprocal of three prizes is 100, and divided by probability reciprocal of each prize. The result is used as the length of prizewinning array. The values of the results increase in sequence.

  1. Random Logic of User Lottery Drawing

When the user draws the lottery, uint value in uint(keccak256(combining string (blockhash of last block + msg.sender +global auto-incrementing index))) at the time of drawing is the random value. Modulo operation is carried out for the above calculated lowest common multiple to get random value. If random value is from the above prizewinning array, it means the successful drawing of the corresponding prize.

1.9 Cautions

hash relies on the hash of last block when the transaction of random value is created. ThunderChain's transaction confirmation is second-level confirmation, but will not immediately synchronize with external transaction record so as to ensure hash of last block transaction will not be for malicious use.

2. Lottery Contract Jackpot Model

Contract item address github

The contract achieves main functions of lottery jackpot model, and mainly includes two contracts, namely LotteryControl control contract and LotteryData data contract. Control contract provides the entry for the developers to access the contract, and processes data contract and saves relevant data.

2.1 Lottery Contract Function

  • Add and remove administrator account address of lottery contract
  • Create lottery
  • Set lottery contract parameter configuration
  • Check lottery contract parameter configuration
  • Run the lottery
  • Participate in the lottery
  • Inquire lottery information
  • Inquire lottery result

2.2 Contract Deployment

  1. Deploy LotteryData contract

  2. Deploy LotteryControl contract

  3. Call setLotteryControl method of LotteryData contract, and set LotteryControl contract address

2.3 Method of Use

The developer or user carries out contract interaction through calling LotteryControl contract method.

2.3.1 Create Lottery

The developer calls newLottery method to create lottery. The method returns event ID, and the developer should save event ID. Subsequent contract method call requires the input of the lottery ID;

After creation, call setLotteryConfig to set event rules. The developer can input parameters for rule configuration according to the needs. The description of configured parameters is as follows.

  // Set lottery configuration
  function setLotteryConfig (
    uint lotteryID,            // lottery ID
    uint startTime,            // event starting time, Unix time stamp
    uint endTime,              // event ending time, Unix time stamp
    bool dayLimit,             // whether to set daily lottery drawing time
    uint dayStartTime,         // daily lottery starting time
    uint dayEndTime,           // daily lottery ending time
    int timesPerItem,          // participant lottery drawing times limit
    uint amountPerAction,      // lottery amount per time unit:LinkToken
    uint openCondition,        // open condition. The lottery mode is 0:jackpot mode. When the jackpot amount reaches prescribed amount, the lottery will be open (unit: LinkToken) 1: opening time mode. Lottery opening at prescribed time (Unix time stamp) 2: address mode. When the participating user account addresses reach prescribed number, the lottery will be open
    uint copies                // how many equal shares of the prize to be distributed
  )

After setLotteryConfig is called, lottery automatically takes effect.

2.3.2 Participate in Lottery

The user participates in lottery by calling joinLottery method. If the user meets the lottery rules, it will be successful participation. The user can check lottery result after the lottery is open;

2.3.3 Open the Lottery

fixed jackpot amount and participating user number mode

When the lottery meets the opening conditions, the contract internally triggers OpenLottery, and the developer can monitor the to judge that lottery opening can be carried out and call openLottery to open the lottery. If the lottery ends, and the monitoring event does not happen, the developer can directly call openLottery to open the lottery.

Fixed lottery opening time mode

When the lottery opening time comes, the developer calls openLottery to open the lottery.

2.3.4 Inquire the Lottery

The lottery finally has the following two statuses after lottery opening. The developer or user can call queryLotteryResult method to check the result.

  • If the lottery opening conditions are met, the contract automatically executes the lottery internally, and sends prizes to the prizewinning users. Lottery status is opened.
  • If the lottery opening conditions are not met, the contract automatically refunds corresponding LinkToken of the participating users internally. Lottery status is refunded.

2.4 Lottery Mechanism

All the LinkToken in the jackpot is equally divided into N parts (the developer can revise contract parameter configuration), and each award will be randomly distributed to lottery participating users successively. One user can get several awards.