From 398f8464faba3a5219d36014916844935280079d Mon Sep 17 00:00:00 2001 From: Lee ByeongJun Date: Thu, 2 Jan 2025 18:37:46 +0900 Subject: [PATCH] update docs --- launchpad/deposit.gno | 42 ++++++++++++++++++++++++++++---- launchpad/reward.gno | 28 +++++++++++++++++++-- launchpad/reward_distributor.gno | 20 ++++++++++++++- 3 files changed, 82 insertions(+), 8 deletions(-) diff --git a/launchpad/deposit.gno b/launchpad/deposit.gno index 7e3ea2a3..c3df45aa 100644 --- a/launchpad/deposit.gno +++ b/launchpad/deposit.gno @@ -25,18 +25,19 @@ func init() { depositStore = NewDepositStore() } -// DepositStore stores deposit-related metadata +// DepositStore manages deposit-related operations and data storage. +// It maintains indices for efficient querying of deposits by various criteria. type DepositStore struct { - // all deposits + // deposits stores all deposit information deposits *avl.Tree // deposit ID -> *Deposit - // deposits by project + // depositsByProject indexes deposits by project and tier depositsByProject *avl.Tree // project ID + tier -> []string(depositIds) - // deposits by user + // depositsByUser indexes deposits by user address depositsByUser *avl.Tree // user address -> []string(depositIds) - // deposits by user & project + // depositsByUserProject indexes deposits by user address and project ID depositsByUserProject *avl.Tree // user address + project ID -> []string(depositIds) } @@ -67,6 +68,19 @@ type DepositManager interface { CollectDeposit(depositId string, user std.Address) (uint64, error) } +// AddDeposit creates a new deposit for the specified project and user. +// +// The deposit is added to all relevant indices for efficient querying. +// +// Parameters: +// - projectId: the ID of the project to deposit into +// - user: the address of the depositor +// - amount: the amount of GNS deposited +// - tier: the tier of the deposit +// +// Returns: +// - depositId: the ID of the deposit +// - error: any error encountered during the process func (ds *DepositStore) AddDeposit(projectId string, user std.Address, amount uint64, tier string) (string, error) { project, exists := projects[projectId] if !exists { @@ -150,6 +164,14 @@ func alreadyDepositedSameTier(ds *DepositStore, user std.Address, projectId, tie return false } +// GetDeposit retrieves deposit information by deposit ID. +// +// Parameters: +// - depositId: the ID of the deposit to retrieve +// +// Returns: +// - *Deposit: the deposit information +// - error: any error encountered during the retrieval func (ds *DepositStore) GetDeposit(depositId string) (*Deposit, error) { value, exists := ds.deposits.Get(depositId) if !exists { @@ -199,6 +221,16 @@ func (ds *DepositStore) GetProjectDeposits(projectId string) ([]*Deposit, error) return deposits, nil } +// CollectDeposit processes a deposit collection request. +// Verifies user authorization and updates relevant project statistics. +// +// Parameters: +// - depositId: the ID of the deposit to collect +// - user: the address of the collector +// +// Returns: +// - uint64: the amount of GNS collected +// - error: any error encountered during the process func (ds *DepositStore) CollectDeposit(depositId string, user std.Address) (uint64, error) { dpst, err := ds.GetDeposit(depositId) if err != nil { diff --git a/launchpad/reward.gno b/launchpad/reward.gno index db76e3aa..47dfb720 100644 --- a/launchpad/reward.gno +++ b/launchpad/reward.gno @@ -31,10 +31,16 @@ type Calculator interface { UpdateRewardSnapshot(pid string) error } -// RewardStore stores reward-related metadata +// RewardStore manages reward calculations and snapshots for projects. +// It tracks accumulated rewards, calculation heights, and maintains reward history. type RewardStore struct { + // accumulatedRewards stores total rewards for each project accumulatedRewards *avl.Tree // project ID -> *u256.Uint + + // lastCalculatedHeights tracks the last block height where rewards were calculated lastCalculatedHeight *avl.Tree // project ID -> uint64 + + // rewardSnapshots stores point-in-time reward state rewardSnapshots *avl.Tree // -> *RewardSnapshot } @@ -46,12 +52,26 @@ func NewRewardStore() *RewardStore { } } +// RewardSnapshot represents a point-in-time capture of reward state. +// It includes the total accumulated reward and tier-specific rewards. type RewardSnapshot struct { Height uint64 AccumulatedRewards *u256.Uint - TierRewards *avl.Tree // key: tier, value: *u256.Uint + TierRewards *avl.Tree // tier -> *u256.Uint } +// CalculateRewards computes rewards for a project up to the specified height. +// +// It returns the total calculated reward and any error encountered. +// The calculation takes into account tier-specific reward rates and durations. +// +// Parameters: +// - pid: the project ID +// - height: the block height up to which rewards are calculated +// +// Returns: +// - *u256.Uint: the total calculated reward +// - error: any error encountered during the calculation func (rs *RewardStore) CalculateRewards(pid string, height uint64) (*u256.Uint, error) { lastHeight, exists := rs.lastCalculatedHeight.Get(pid) lstHeight := uint64(0) @@ -155,6 +175,8 @@ func calcTierRewardPerBlock(tier *Tier, ratio uint64) *u256.Uint { return amountPerBlock } +// GetAccumulatedRewards returns the total accumulated rewards for a project. +// If no rewards exist, returns zero. func (rs *RewardStore) GetAccumulatedRewards(pid string) (*u256.Uint, error) { reward, exists := rs.accumulatedRewards.Get(pid) if !exists { @@ -163,6 +185,8 @@ func (rs *RewardStore) GetAccumulatedRewards(pid string) (*u256.Uint, error) { return reward.(*u256.Uint), nil } +// UpdateRewardSnapshot creates a new snapshot of the current reward state. +// It captures both total and tier-specific rewards at the current block height. func (rs *RewardStore) UpdateRewardSnapshot(pid string) error { height := uint64(std.GetHeight()) diff --git a/launchpad/reward_distributor.gno b/launchpad/reward_distributor.gno index b0bdde7b..90c4847e 100644 --- a/launchpad/reward_distributor.gno +++ b/launchpad/reward_distributor.gno @@ -17,6 +17,8 @@ import ( var rewardDistributor = NewRewardDistributor() +// DistributionRecord represents a single reward distribution event. +// It captures all relevant information about the distribution. type DistributionRecord struct { User std.Address ProjectId string @@ -25,9 +27,16 @@ type DistributionRecord struct { DistributeTime uint64 } +// RewardDistributor handles the distribution of rewards to users. +// It manages pending rewards, distribution history, and batch processing. type RewardDistributor struct { + // pendingRewards tracks unreleased rewards by user and project pendingRewards *avl.Tree // userAddr:projectId -> *u256.Uint + + // distributionHistory maintains a record of all distributions distributionHistory *avl.Tree // userAddr:projectId:height -> *DistributionRecord + + // lastUpdateHeight tracks the last update height per project lastUpdateHeight *avl.Tree // projectId -> uint64 } @@ -39,6 +48,8 @@ func NewRewardDistributor() *RewardDistributor { } } +// PendingRewards returns the amount of undistributed rewards for a user in a project. +// Returns zero if no pending rewards exist. func (rd *RewardDistributor) PendingRewards(user std.Address, pid string) (*u256.Uint, error) { key := generateRewardKey(user, pid) value, exists := rd.pendingRewards.Get(key) @@ -49,7 +60,8 @@ func (rd *RewardDistributor) PendingRewards(user std.Address, pid string) (*u256 return value.(*u256.Uint), nil } -// DistributeRewards distributes rewards to all depositors in a specific project +// DistributeRewards processes rewards distribution for an entire project. +// Calculates and queues rewards for all eligible deposits in the project. func (rd *RewardDistributor) DistributeRewards(pid string) error { _, exists := projects[pid] if !exists { @@ -91,6 +103,8 @@ func (rd *RewardDistributor) DistributeRewards(pid string) error { return nil } +// DistributeUserRewards processes reward distribution for a specific user. +// Returns the distributed amount and any error encountered. func (rd *RewardDistributor) DistributeUserReward(user std.Address, pid string) (*u256.Uint, error) { key := generateRewardKey(user, pid) @@ -138,6 +152,8 @@ func (rd *RewardDistributor) DistributeUserReward(user std.Address, pid string) return reward, nil } +// BatchDistribute processes reward distribution for multiple users in batch. +// Optimizes gas usage by combining multiple distributions. func (rd *RewardDistributor) BatchDistribute(users []std.Address, pid string) error { for _, user := range users { _, err := rd.DistributeUserReward(user, pid) @@ -212,6 +228,8 @@ func generateDistributionHistoryKey(key string, height uint64) string { return ufmt.Sprintf("%s:%d", key, height) } +// isRewardClaimable checks if a deposit is eligible for reward collection. +// Verifies deposit maturity and claim conditions. func isRewardClaimable(dpst *Deposit) bool { currentHeight := uint64(std.GetHeight()) return currentHeight >= dpst.claimableHeight &&