Intro
This article describes the general principles of the Immortal Lottery — a decentralized autonomous application designed to work continuously at various blockchains after deployment without any maintenance requirements.
Read more about the Immortal Lottery here.
This article should serve as a reference documentation of lottery functioning across multiple platforms. Some sections are marked as EVM-specific and only describe things related to the reference implementation at Callisto Network. These may not affect re-implementations.
Lottery contracts
The lottery is composed of multiple smart-contracts:
1. Lottery contract — responsible for the logic of playing rounds
2. Entropy — responsible for collecting entropy from users
3. Token — standard ERC223 token contract, tokens can be staked to allow the owner to claim a portion of lottery fees
4. Reward pool — distributes the collected commission between token holders
Lottery logics
The lottery is held in rounds. Each round must be manually started by a user and the lottery does not automatically start a new round after the previous one has finished.
EVM-specific: To start the round a user must call the start_new_round() function and provide the initial deposit. There is a minimal deposit amount currently set to 1000 CLO. If a user decides to increase his deposit then he can deposit more CLO to the contract but this function suffers a technical limitation and the number of possible deposits is restricted to 20 deposits per account per round. Deposits count resets each round. A player can use the same account in a new round even if the total number of deposits was exhausted during the previous round. A player can always use multiple accounts if necessary.
The lottery has three phases that follow one another in succession:
- Inactive (the lottery is not running a round)
- Deposits (a round is running and deposits are allowed, entropy providers can supply entropy hashes to the contract)
- Reveal (a round is running and entropy providers are revealing their entropy inputs, players are awaiting for this to finish)
Phases have fixed duration. EVM-specific: The current phase is determined by the timestamp of the round start.
After the reveal phase has ended the lottery round is considered completed.
A round can potentially complete successfully or fail depending on the ratio of entropy collateral and reward pool. If the round is completed successfully then there is a winner and he should be paid a reward. If the round fails then every user is allowed to withdraw their deposit back (without a fee).
CLO-specific: currently the entropy criteria is halted and the rounds always complete successfully. It requires live testing to determine the ratio of entropy collateral / reward which is sufficient to say that the round was “fair”.
There will be multiple “lottery logical contracts” set up with different configurations. The contracts will be active at the same time but will have different entropy threshold, minimal deposit, round duration and other inner constants.
Completion of a round
Each round should be completed manually. At this moment the contract is sending the reward to the winner if the round was successful and the round fees are being distributed.
Any address can perform the completion of a round. However the winner of the round is mostly interested in faster completion because he will be paid the reward at that time.
EVM-specific: A user must call the finish_round() function and provide the winners address. The round reward will be sent to the winner. The address of a winner can be calculated off-chain by the function caller or external UI.
Upon completion of a round the lottery will enter the Inactive phase.
Starting a new round
A round must be started manually by a user. The lottery does not run “empty” rounds.
EVM-specific: To launch a new round a user must call the start_new_round() function and provide the deposit he is willing to participate with.
When the round is started the lottery contract will start accepting deposits. The lottery round can not be started if the previous round winner is not paid even if the previous round time runs out.
Staking tokens for rewards
All main lottery contracts send lottery fees to the same reward pool contract. A token holder can stake his IML tokens in the reward pool contract to lock the tokens for a fixed period of time. At the end of the staking round he will be allowed to (1) withdraw reward only or (2) tokens and reward similar to Cold Staking v1 formula.