docs: comments, docs, ...

Author: r3v4s

contract/r/gnoswap/common/tick_math.gno

@@ -270,23 +270,23 @@ func adjustRatio(ratio, msb *u256.Uint) *u256.Uint {
 //
 // This function iteratively squares the ratio and adjusts the result to compute the log base 2, which will determine the tick value.
 func calculateLog2(msb, ratio *u256.Uint) *i256.Int {
-	_msb := i256.FromUint256(msb)
-	_128 := i256.NewInt(128)
+	msbInt := i256.FromUint256(msb)
+	constant128 := i256.NewInt(128)
 
-	log_2 := i256.Zero().Sub(_msb, _128)
-	log_2 = log_2.Lsh(log_2, 64)
+	log2Result := i256.Zero().Sub(msbInt, constant128)
+	log2Result = log2Result.Lsh(log2Result, 64)
 
-	for i := 63; i >= 51; i-- {
+	for bitPosition := 63; bitPosition >= 51; bitPosition-- {
 		ratio = new(u256.Uint).Mul(ratio, ratio)
 		ratio = ratio.Rsh(ratio, 127)
 
-		f := i256.FromUint256(new(u256.Uint).Rsh(ratio, 128))
+		shiftFactor := i256.FromUint256(new(u256.Uint).Rsh(ratio, 128))
 
-		// log_2 = log_2 | (f << i)
-		log_2 = i256.Zero().Or(log_2, i256.Zero().Lsh(f, uint(i)))
+		// log2Result = log2Result | (shiftFactor << bitPosition)
+		log2Result = i256.Zero().Or(log2Result, i256.Zero().Lsh(shiftFactor, uint(bitPosition)))
 
-		// ratio = ratio >> uint64(f)
-		ratio = ratio.Rsh(ratio, uint(f.Uint64()))
+		// ratio = ratio >> uint64(shiftFactor)
+		ratio = ratio.Rsh(ratio, uint(shiftFactor.Uint64()))
 	}
 
 	// handle the remaining bits
@@ -295,12 +295,12 @@ func calculateLog2(msb, ratio *u256.Uint) *i256.Int {
 		ratio = new(u256.Uint).Mul(ratio, ratio)
 		ratio = new(u256.Uint).Rsh(ratio, 127)
 
-		f := i256.FromUint256(new(u256.Uint).Rsh(ratio, 128))
+		shiftFactor := i256.FromUint256(new(u256.Uint).Rsh(ratio, 128))
 
-		log_2 = i256.Zero().Or(log_2, i256.Zero().Lsh(f, 50))
+		log2Result = i256.Zero().Or(log2Result, i256.Zero().Lsh(shiftFactor, 50))
 	}
 
-	return log_2
+	return log2Result
 }
 
 // getTickValue determines the tick value corresponding to a given sqrtPriveX96.
@@ -310,17 +310,17 @@ func calculateLog2(msb, ratio *u256.Uint) *i256.Int {
 func getTickValue(log2 *i256.Int, sqrtPriceX96 *u256.Uint) int32 {
 	// ref: https://github.com/Uniswap/v3-core/issues/500
 	// 2^64 / log2 (√1.0001) = 255738958999603826347141
-	log_sqrt10001 := i256.Zero().Mul(log2, i256.MustFromDecimal("255738958999603826347141"))
+	logSqrtRatioMultiplier := i256.Zero().Mul(log2, i256.MustFromDecimal("255738958999603826347141"))
 
 	// ref: https://ethereum.stackexchange.com/questions/113844/how-does-uniswap-v3s-logarithm-library-tickmath-sol-work/113912#113912
 	// 0.010000497 x 2^128 = 3402992956809132418596140100660247210
-	tickLow256 := i256.Zero().Sub(log_sqrt10001, i256.MustFromDecimal("3402992956809132418596140100660247210"))
+	tickLow256 := i256.Zero().Sub(logSqrtRatioMultiplier, i256.MustFromDecimal("3402992956809132418596140100660247210"))
 	tickLow256 = tickLow256.Rsh(tickLow256, 128)
 	tickLow := int32(tickLow256.Int64())
 
 	// ref: https://ethereum.stackexchange.com/questions/113844/how-does-uniswap-v3s-logarithm-library-tickmath-sol-work/113912#113912
 	// 0.856 x 2^128 = 291339464771989622907027621153398088495
-	tickHi256 := i256.Zero().Add(log_sqrt10001, i256.MustFromDecimal("291339464771989622907027621153398088495"))
+	tickHi256 := i256.Zero().Add(logSqrtRatioMultiplier, i256.MustFromDecimal("291339464771989622907027621153398088495"))
 	tickHi256 = tickHi256.Rsh(tickHi256, 128)
 	tickHi := int32(tickHi256.Int64())
 

contract/r/gnoswap/gns/gns.gno

@@ -25,11 +25,11 @@ var (
 	privateLedger *grc20.PrivateLedger
 	UserTeller    grc20.Teller
 
-	leftEmissionAmount   uint64
-	mintedEmissionAmount uint64
-	lastMintedHeight     int64
+	leftEmissionAmount   uint64 // amount of GNS can be minted for emission
+	mintedEmissionAmount uint64 // amount of GNS that has been minted for emission
+	lastMintedHeight     int64  // last block height that gns was minted for emission
 
-	burnAmount uint64
+	burnAmount uint64 // amount of GNS that has been burned
 )
 
 func init() {

contract/r/gnoswap/gns/halving.gno

@@ -162,6 +162,8 @@ func (h *HalvingData) setAmountPerBlock(year int64, amount uint64) {
 	h.amountPerBlock[year-1] = amount
 }
 
+// initialize initializes the halving data based on release schedule
+// ref: https://docs.gnoswap.io/gnoswap-token/release-schedule
 func (h *HalvingData) initialize(startHeight, startTimestamp int64) {
 	for year := HALVING_START_YEAR; year <= HALVING_END_YEAR; year++ {
 		// set max emission amount per year

contract/r/gnoswap/gov/doc.gno

@@ -1,2 +1,5 @@
-// Package gov manages the governance of the gnoswap protocol, including proposal creation, voting, and execution.
+// Package gov provides Gnoswap's governance system through three packages:
+// 1. governance: Handles proposal creation, voting, and execution
+// 2. staker: Manages GNS staking, delegation, and reward distribution
+// 3. xgns: Implements the xGNS token representing staked GNS
 package gov

contract/r/gnoswap/gov/governance/doc.gno

@@ -0,0 +1,5 @@
+// Package governance implements proposal lifecycle management and voting.
+// It supports text proposals, parameter changes, and community pool spending.
+// Proposals go through creation, voting, and execution phases with configurable
+// parameters for voting delays, periods, and thresholds.
+package governance

contract/r/gnoswap/gov/governance/execute.gno

@@ -14,6 +14,11 @@ import (
 	en "gno.land/r/gnoswap/v1/emission"
 )
 
+// Governance can execute multiple messages in a single proposal
+// each message is a string with the following format:
+// <pkgPath>*EXE*<function>*EXE*<params>
+// To execute a message, we need to parse the message and call the corresponding function
+// with the given parameters
 const (
 	EXECUTE_SEPARATOR = "*EXE*"
 )

contract/r/gnoswap/gov/governance/proposal.gno

@@ -22,6 +22,9 @@ var (
 	latestProposalByProposer = avl.NewTree() // proposer -> proposalId
 )
 
+// Governance can execute multiple messages in a single proposal
+// To separate the messages, we use this separator
+// Look for ProposeParameterChange() for more details
 const (
 	GOV_SPLIT = "*GOV*"
 )
@@ -175,6 +178,10 @@ func ProposeCommunityPoolSpend(
 
 // ProposeParameterChange creates a new parameter change with the given data
 // It checks if the proposer is eligible to create a proposal and if they don't have an active proposal.
+// Through gnoswap interface, following string will be passed in for executions:
+// <pkgPath>*EXE*<function>*EXE*<params>*GOV*<pkgPath>*EXE*<function>*EXE*<params>
+// *GOV* is used to separate the messages
+//
 // Returns the proposal ID
 // ref: https://docs.gnoswap.io/contracts/governance/proposal.gno#proposeparameterchange
 func ProposeParameterChange(
@@ -392,6 +399,9 @@ func (u *proposalStateUpdater) updateExecutionState() {
 	}
 }
 
+// checkEnoughXGnsToPropose checks if the proposer has enough xGNS to propose a proposal.
+// ref: https://docs.gnoswap.io/core-concepts/governance#scope-of-proposals-5
+// It returns a boolean indicating if the proposer has enough xGNS, the balance of xGNS, and the threshold of xGNS.
 func checkEnoughXGnsToPropose(proposer std.Address) (bool, uint64, uint64) {
 	xGNSBalance := xgns.BalanceOf(proposer)
 

contract/r/gnoswap/gov/governance/type.gno

@@ -7,6 +7,7 @@ import (
 )
 
 // Config represents the configuration of the governor contract
+// ref: https://docs.gnoswap.io/core-concepts/governance#scope-of-proposals-5
 type Config struct {
 	// How long after a proposal is created does voting starrt
 	VotingStartDelay uint64

contract/r/gnoswap/gov/governance/utils.gno

@@ -11,6 +11,7 @@ import (
 	"gno.land/p/demo/ufmt"
 )
 
+// Retrieves a proposal by its ID
 func mustGetProposal(proposalId uint64) ProposalInfo {
 	result, exists := proposals.Get(formatUint(proposalId))
 	if !exists {
@@ -23,6 +24,7 @@ func mustGetProposal(proposalId uint64) ProposalInfo {
 	return result.(ProposalInfo)
 }
 
+// Retrieves a vote by its key
 func mustGetVote(key string) bool {
 	vote, exists := votes.Get(key)
 	if !exists {
@@ -38,8 +40,10 @@ func mustGetVote(key string) bool {
 func getVoteInfoFromKey(voteKey string) (voteWithWeight, bool) {
 	mustGetVote(voteKey)
 
+	// Splits the vote key into proposal ID and user address
 	pid, addr := divideVoteKeyToProposalIdAndUser(voteKey)
 
+	// Retrieves user vote information
 	voteInfo, exists := getUserVote(addr, pid)
 	if !exists {
 		panic(addDetailToError(
@@ -51,15 +55,18 @@ func getVoteInfoFromKey(voteKey string) (voteWithWeight, bool) {
 	return voteInfo, true
 }
 
+// Retrieves vote information by key
 func mustGetVoteInfo(voteKey string) voteWithWeight {
 	voteInfo, _ := getVoteInfoFromKey(voteKey)
 	return voteInfo
 }
 
+// Iterates over an AVL tree and applies a callback function to each element
 func iterTree(tree *avl.Tree, cb func(key string, value interface{}) bool) {
 	tree.Iterate("", "", cb)
 }
 
+// Converts a string to an integer, panics if conversion fails
 func strToInt(str string) int {
 	res, err := strconv.Atoi(str)
 	if err != nil {
@@ -69,13 +76,15 @@ func strToInt(str string) int {
 	return res
 }
 
+// Converts a boolean vote to a string representation
 func voteToString(b bool) string {
 	if b {
 		return "yes"
 	}
 	return "no"
 }
 
+// Marshals a JSON node to a string, panics if marshalling fails
 func marshal(data *json.Node) string {
 	b, err := json.Marshal(data)
 	if err != nil {
@@ -85,10 +94,12 @@ func marshal(data *json.Node) string {
 	return string(b)
 }
 
+// Encodes a string to base64
 func b64Encode(data string) string {
 	return string(base64.StdEncoding.EncodeToString([]byte(data)))
 }
 
+// Decodes a base64 string, panics if decoding fails
 func b64Decode(data string) string {
 	decoded, err := base64.StdEncoding.DecodeString(data)
 	if err != nil {
@@ -97,15 +108,18 @@ func b64Decode(data string) string {
 	return string(decoded)
 }
 
+// Returns the package path of the previous realm
 func prevRealm() string {
 	return std.PrevRealm().PkgPath()
 }
 
+// Returns the address and package path of the previous realm
 func getPrev() (string, string) {
 	prev := std.PrevRealm()
 	return prev.Addr().String(), prev.PkgPath()
 }
 
+// Formats an unsigned integer to a string
 func formatUint(v interface{}) string {
 	switch v := v.(type) {
 	case uint8:
@@ -119,10 +133,12 @@ func formatUint(v interface{}) string {
 	}
 }
 
+// Formats a boolean to a string
 func formatBool(v bool) string {
 	return strconv.FormatBool(v)
 }
 
+// Parses a string to an integer, panics if parsing fails
 func parseInt(s string) int {
 	num, err := strconv.ParseInt(s, 10, 64)
 	if err != nil {
@@ -131,6 +147,7 @@ func parseInt(s string) int {
 	return int(num)
 }
 
+// Parses a string to an unsigned 64-bit integer, panics if parsing fails
 func parseUint64(s string) uint64 {
 	num, err := strconv.ParseUint(s, 10, 64)
 	if err != nil {
@@ -139,6 +156,7 @@ func parseUint64(s string) uint64 {
 	return num
 }
 
+// Parses a string to a boolean, panics if parsing fails
 func parseBool(s string) bool {
 	switch s {
 	case "true":

contract/r/gnoswap/gov/governance/vote.gno

@@ -29,10 +29,15 @@ var (
 	accumNoVotes  = make(map[uint64]uint64) // proposalId -> no
 )
 
+// createVoteKey creates a vote key for a given proposal ID and voter address
 func createVoteKey(pid uint64, voter string) string {
 	return ufmt.Sprintf("%d:%s", pid, voter)
 }
 
+// getVote gets a vote for a given proposal ID and voter address
+// Returns:
+// - vote: the vote for the given proposal ID and voter address
+// - exists: a boolean indicating if user has voted on the proposal
 func getVote(pid uint64, voter string) (bool, bool) {
 	value, exists := votes.Get(createVoteKey(pid, voter))
 	if !exists {
@@ -46,6 +51,7 @@ func setVote(pid uint64, voter string, vote bool) {
 	votes.Set(voteKey, vote)
 }
 
+// createUserVoteKey creates a user vote key for a given voter address and proposal ID
 func createUserVoteKey(voter std.Address, pid uint64) string {
 	return ufmt.Sprintf("%s:%d", voter.String(), pid)
 }