STETH Pool

The main pool contract

This is designed for managing a pool of stETH deposits and distributing rewards to lucky users. It allows users to deposit, and withdraw stETH, claim rewards, tracks user deposit information, calculates rewards based on user deposits, and supports the creation and finalization of epochs for reward distribution. The contract can be configured with various parameters, such as reward allocation percentages and minimum deposit amounts.

Structs

Name	Elements
PrizeDetails	address winner uint256 prizeAmount bool claimed
EpochResult	PrizeDetails first PrizeDetails second PrizeDetails third bool finalized uint256 totalPrize uint256 duration uint256 createdTimeStamp uint256 totalParticipant
rewardAllocation	uint256 first uint256 second uint256 third
userInfo	address userAddress uint256 DepositAmount uint256 registeredDate uint256 Lastupdated
ChangeArray	uint256 oldAmount uint256 newAmount uint256 updatedBlock
userChangeHistory	bool changedwithinEpoch ChangeArray[] historyArray
rewardHistory	uint256 EpochNumber uint256 position uint256 PrizeAmount
claimableRewardInfo	uint256 claimable rewardHistory[] rewardHistoryArray uint256[] temporaryNotClaimedEpochArray

Modifiers

Name	Params	Description
validEpoch	uint256 epochNumber	Ensures that the provided epoch number is valid (less than or equal to the latest epoch).
contractStarted		Checks whether the contract has started (epoch length is greater than zero).
onlyRewardDistributor		Restricts access to only the reward distributor.
onlyOwner		Restricts access to only the owner of the contract.
onlyController		Restricts access to only the controller of the contract.
onlyRouter		Restricts access to only the router
nonReentrant		Prevents reentrancy by checking a status variable to ensure that only one function call can execute at a time.

View functions

Name	Modifiers Implemented	Description
getUserID(address user)		Returns the user's userID stored within the contract.
getPoolTVL()		This function returns the total amount of assets (stETH) currently deposited in the contract and is usually used by Front-end team
getCurrentEpochReward()		This function calculates and returns the current epoch's reward balance. It subtracts the total pool value from the current balance (balanceOf in stETH's contract) to determine the rewards available for distribution.
getClaimable(address user)		For a given user, this function returns the amount of rewards they can claim. It indicates the total rewards earned but not yet claimed by the user. Everytime the user claims, it would be reset to 0
getWinningHistory(address user)		This function retrieves an array of reward history for a specific user. It shows the user's past rewards earned, including the epoch number, winning position, and prize amount.
getBalanceChangeHistory(address user, uint256 epochNumber)		Given a user's address and an epoch number, this function provides a history of changes in the user's deposit balance within that epoch. It includes old and new balance values along with the timestamp of the update. This function is used to calculate ticket amounts of the user in each epoch
getUserAmount()		The total number of registered users within the contract. It helps track the user count.
getUserDepositInfo(address user)		For a specified user address, this function returns a userInfo struct containing details about their deposit, registration date, and last update timestamp.
getAccumulatedTicketwithoutDecimal(uint256 epochNumber, address user)		Within a specific epoch and for a given user, this function provides the accumulated ticket amount without decimal precision. There may not be any items inside if the users didn't interact with the contract within the given epoch. This is used to calculate the user's ticket amount in each epoch.
getTicketAmount(uint256 epochNumber, address user)		This function calculates and returns the ticket amount for a user in a specific epoch. It considers various factors, including the user's deposit changes and participation period.
getTokenUsing()		Returns the address of the token used in the contract.
getLatestEpoch()		Provides the latest epoch number, allowing users to stay up to date with the current state of the contract.
getEpochLength()		Returns the total number of epochs that have occurred within the contract.
getEpochInfo(uint256 epochNumber)		Given an epoch number, this function retrieves and returns the details of that specific epoch, including prize distribution and participation information.
getRewardAllocationPercentage()		Returns the reward allocation percentages, specifying how rewards are distributed among the top three participants in an epoch.

Write functions

Name	Modifiers Implemented	Description
initialize(address registryAddress)		This function is responsible for initializing the contract with the provided registry address. It sets the contract's registry to the specified address. This function can only be called once to ensure proper contract initialization.
changeRegistryContractAddr(address registryAddress)	onlyOwner()	This function allows the contract owner to change the registry contract address after deployment. It provides flexibility to update the registry contract address if needed.
depositFor(address user, uint256 amount)	onlyRouter() nonReentrant() contractStarted()	This function enables the router to deposit tokens on behalf of a user. It updates the user's deposit information, including the deposited amount and timestamp. It also increases the total value locked (TVL) in the pool. This function ensures that the contract is in a started state and prevents reentrant calls to maintain data consistency and to avoid any undesirable actions. This function would also specially adjust the accumulated tickets of a user so that at the end of the epoch, his/her tickets can be accurately calculated
withdrawFor(address user, uint256 amount)	onlyRouter() nonReentrant() contractStarted()	This function allows the router to initiate token withdrawals on behalf of a user. It updates the user's deposit information and decreases the TVL in the pool. Similar to the depositFor function, it checks the contract's started state, prevents reentrancy and also update the user's accumulated tickets
claimRewardsFor(address user)	onlyRouter() nonReentrant() contractStarted()	The router can use this function to claim rewards on behalf of a user. It transfers claimable rewards to the Router and updates the contract state to mark the rewards as claimed. It ensures that the contract is in a started state and prevents reentrant calls. After this function is invoked by the Router, the Router itself would transfer the rewards to the user(msg.sender who called the Router)
config(address token, uint256 decimal, uint256 minAmount, uint256 duration)	onlyController()	This function is used by the controller to configure contract parameters, including the token address, decimal precision, minimum deposit amount, and epoch duration.
setRewardRatio(uint256 firstP, uint256 secondP, uint256 thirdP, uint256 percentageSUM)	onlyController()	The controller can set the reward allocation percentages for first, second, and third place winners using this function. The sum of these percentages should equal percentageSUM. (Eg: 50% + 30% + 20% must equal to 100%)
finalizeEpochTicketandParticipantInfo(uint256 epochNumber)	onlyRewardDistributor()	This function is called by the reward distributor to finalize an epoch by calculating the total number of participants. *This is not an important function
finalizeEpoch(uint256 epochNumber, address firstWinner, address secondWinner, address thirdWinner, uint256 totalPrize)	onlyRewardDistributor()	The reward distributor uses this function to finalize an epoch by specifying the first, second, and third place winners and distributing the total prize among them. It also marks the epoch as finalized, and would transfer the rewards to the Reward Reserve contract to store the rewards before the user claiming it.
createNewEpoch()	onlyRewardDistributor()	This function is used by the reward distributor to create a new epoch in the contract. It initializes a new epoch with empty prize details and increments the epoch count. If the last epoch is not ended, the transaction will revert.