Repository: gnoswap-labs/gnoswap
Pull request #567: update docs
Author: login: notJoon
Created: 2025-03-07T11:30:34Z | Merged: 2025-03-07T13:32:01Z

add more docs


Diff:
diff --git a/contract/p/gnoswap/consts/consts.gno b/contract/p/gnoswap/consts/consts.gno
index b659c65af9..87332e6ba2 100644
--- a/contract/p/gnoswap/consts/consts.gno
+++ b/contract/p/gnoswap/consts/consts.gno
@@ -4,7 +4,7 @@ import (
 	"std"
 )
 
-// ADDRESS
+// INITIAL ADDRESSES
 const (
 	ADMIN   std.Address = "g17290cwvmrapvp869xfnhhawa8sm9edpufzat7d"
 	DEV_OPS std.Address = "g1mjvd83nnjee3z2g7683er55me9f09688pd4mj9"
@@ -20,7 +20,7 @@ const (
 	UGNOT_MIN_DEPOSIT_TO_WRAP uint64 = 1000
 )
 
-// CONTRACT PATH & ADDRESS
+// INITIAL CONTRACT PATH & ADDRESS
 const (
 	POOL_PATH string      = "gno.land/r/gnoswap/v1/pool"
 	POOL_ADDR std.Address = "g148tjamj80yyrm309z7rk690an22thd2l3z8ank"
diff --git a/contract/r/gnoswap/emission/README.md b/contract/r/gnoswap/emission/README.md
new file mode 100644
index 0000000000..044054f1c4
--- /dev/null
+++ b/contract/r/gnoswap/emission/README.md
@@ -0,0 +1,43 @@
+# Emission
+
+## Overview
+
+The emission contract manages minting and distributing the `GNS` token.
+
+## Features
+
+### Token Emission and Distribution
+
+- Mints `GNS` tokens on a block generation time basis (initially set [here](https://github.com/gnoswap-labs/gnoswap/blob/main/contract/p/gnoswap/consts/consts.gno#L126), but can be changed by governance)
+- Distributes tokens to the set targets
+- Tracks undistributed tokens and include it in future distribution cycles
+
+### Distribution Targets
+
+Tokens are distributed to four main targets as follows by default:
+
+- **Liquidity Staker**: 75%
+- **DevOps Team**: 20%
+- **Community Pool**: 5%
+- **Governance Stakers**: 0%
+
+### Distribution Ratio Management
+
+- Governance or admin can adjust token distribution ratio
+- Distribution percentages are tracked in basis points (1 bp = 0.01%)
+- Total distribution must always equal 100% (10,000 basis points)
+
+### Undistributed Token Handling
+
+- Any tokens not distributed in a cycle are tracked
+- Undistributed tokens are included in the next distribution cycle
+
+### Halving
+
+There is a halving mechanism that reduces the issuance amount by half every two years
+
+### Callback Mechanisms
+
+Provides callback function for inter-contract communication. This will notify relevant components when distribution ratios change. Details to be found on our [bridge contract](https://github.com/gnoswap-labs/gnoswap/tree/main/contract/r/gnoswap/bridge#bridge).
+
+For more details about the emission, check out the [GnoSwap docs](https://docs.gnoswap.io/gnoswap-token/emission).
diff --git a/contract/r/gnoswap/gns/README.md b/contract/r/gnoswap/gns/README.md
new file mode 100644
index 0000000000..bff86617a6
--- /dev/null
+++ b/contract/r/gnoswap/gns/README.md
@@ -0,0 +1,32 @@
+# GNS Token
+
+The `GNS` token is the governance and main utility token of the GnoSwap protocol
+
+## Token Implementation
+
+- Follows the `grc20` token specs ([grc spec](https://github.com/gnolang/gno/tree/master/examples/gno.land/p/demo/grc))
+- Symbol: `GNS`
+- Decimals: 6
+- Max Supply: 1_000_000_000 (1B)
+
+You can find the detailed tokenomics of GNS [here](https://docs.gnoswap.io/gnoswap-token/whats-gns).
+
+## Emission Mechanism
+
+- Block-based token emission with predefined schedule
+- Token emission follows a halving model over 12 years
+- Each halving period adjusts the amounts of tokens minted per block
+
+## Halving Schedule
+
+- 12 years emission period devided into halving periods
+
+| Years | Description |
+| --- | --- |
+| 1-2 | Full emission rate |
+| 3-4 | 50% of initial emission rate |
+| 5-6 | 25% of initial emission rate |
+| 7-8 | 12.5% of initial emission rate |
+| 9-12 | 6.25% of initial emission rate |
+
+For details about the emission and distribution of the GNS tokens, refer to our [emission contract](https://github.com/gnoswap-labs/gnoswap/tree/main/contract/r/gnoswap/emission).
diff --git a/contract/r/gnoswap/launchpad/README.md b/contract/r/gnoswap/launchpad/README.md
new file mode 100644
index 0000000000..571c918844
--- /dev/null
+++ b/contract/r/gnoswap/launchpad/README.md
@@ -0,0 +1,23 @@
+# Launchpad
+
+The **GnoSwap Launchpad** is a decentralized token launching platform built on **gno.land**, enabling new projects to launch tokens in a **fair, transparent, and trustless** manner.
+
+## Key Concepts
+
+1. "Lossless" Exposure to Early-Stage Projects
+GnoSwap Launchpad allows **$GNS holders** to acquire new project tokens **without spending their principal $GNS**. Users lock their **$GNS tokens** in a Launchpad Pool for a fixed period and receive project tokens **pro-rata** while their staked $GNS remains secured in the **xGNS Governance Contract**. After maturity, the same amount of $GNS is returned, ensuring a **"lossless" participation model**.
+
+2. Pool Diversity
+Users can choose from **three different pools**, each with varying lock-up periods and reward structures:
+- **1 Month** – Short-term commitment, moderate rewards.
+- **3 Months** – Balanced duration and rewards.
+- **6 Months** – Longer commitment, higher token rewards.
+
+While $GNS remains locked, **project token rewards are liquid** and can be claimed at any time.
+
+3. Yield-Redirection-Based Funding
+GnoSwap Launchpad uses a **yield-redirection mechanism** to fund project token rewards.  
+- Users' **$GNS deposits** are **staked** in the [xGNS Governance Contract](https://github.com/gnoswap-labs/gnoswap/tree/main/contract/r/gnoswap/gov), earning **Protocol Fee Rewards**.  
+- Instead of being returned to users, these **rewards are redirected** to the **Project Owner** in exchange for **newly launching project tokens**.  
+
+For more information about the launchpad feature, refer to: https://docs.gnoswap.io/core-concepts/launchpad
diff --git a/contract/r/gnoswap/protocol_fee/README.md b/contract/r/gnoswap/protocol_fee/README.md
new file mode 100644
index 0000000000..4604b795a1
--- /dev/null
+++ b/contract/r/gnoswap/protocol_fee/README.md
@@ -0,0 +1,20 @@
+# Protocol Fee
+
+## Overview
+
+The Protocol Fee contract manages assets collected as protocol fees across the platform and distributes them to xGNS holders via the `gov/staker` contract.
+
+## Fee
+
+### Collection
+
+- Accumulates protocol fees from various operations ([details](https://docs.gnoswap.io/core-concepts/fees#protocol-fees)).
+- Tracks collected fees by token type.
+- Only the **pool**, **router**, and **staker** contracts can contribute fees to the collection.
+
+### Distribution
+
+- Distributes collected fees between governance stakers and DevOps.
+- Default distribution: **100% to `gov/stakers`, 0% to `DevOps`** (initially).
+- Distribution percentages are configurable by governance.
+- Only the `gov/staker` contract can trigger fee distribution.
diff --git a/contract/r/gnoswap/rbac/README.md b/contract/r/gnoswap/rbac/README.md
new file mode 100644
index 0000000000..58631ce201
--- /dev/null
+++ b/contract/r/gnoswap/rbac/README.md
@@ -0,0 +1,5 @@
+# RBAC (Realm)
+
+This package implements p/rbac at the realm level. In particular, it is used to store states such as permissions for each contract.
+
+For more information, please refer to the documentation in [p/rbac](contract/p/gnoswap/rbac/README.md).
diff --git a/contract/r/gnoswap/referral/README.md b/contract/r/gnoswap/referral/README.md
new file mode 100644
index 0000000000..b51af74f48
--- /dev/null
+++ b/contract/r/gnoswap/referral/README.md
@@ -0,0 +1,17 @@
+# Referral
+
+The Referral contract implementation for managing referral relationships in the GnoSwap. It provides functionality to register, update, and remove referral relationships between addresses.
+
+## Features
+
+- Register referral relationships between addresses
+- Update existing referral relationships
+- Remove referral relationships
+- Query referral information
+- Rate limiting for operations (24-hour cooldown period)
+
+### Keeper
+
+The underlying implementation handles the actual storage and validation of referral relationships using an AVL tree data structure.
+
+For the implementation details, refer to the [referral doc.gno](https://github.com/gnoswap-labs/gnoswap/blob/main/contract/r/gnoswap/referral/doc.gno).


Reviews:
user: login: dongwon8247
body: @notJoon Apply this, please.
state: CHANGES_REQUESTED
author_association: MEMBER
submitted_at: 2025-03-07T13:10:08Z
user: login: dongwon8247
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-07T13:25:24Z

Review comments:
diff_hunk: @@ -4,7 +4,7 @@ import (
 	"std"
 )
 
-// ADDRESS
+// Initial ADDRESSES
path: contract/p/gnoswap/consts/consts.gno
user: login: dongwon8247
body: ```suggestion
// INITIAL ADDRESSES
```
created_at: 2025-03-07T12:37:19Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,42 @@
+# Emission
+
+## Overview
+
+Emission implements the token emission and distribution system for `GNS` tokens on the `gnoswap` protocol. It handles the minting and fair distribution of tokens to various stakeholders according to predefined ratios.
+
+## Features
+
+### Token Emission and Distribution
+
+- Mints new `GNS` tokens at regular interval based on block height.
+- Distributes tokens accroding to configurable ratios to multiple stakeholders
+- Tracks undistributed tokens for inclusion in future distribution cycles
+
+### Distribution Targets
+
+Tokens are distributed to four main stakeholder groups:
+
+- **Liquidity Staker**: 75% (default)
+- **DevOps Team**: 20% (default)
+- **Community Pool**: 5% (default)
+- **Governance Stakers**: 0% (default)
+
+### Distribution Ratio Management
+
+- Administrators can adjust token distribution ratios
+- Governance processes can modify distribution ratios
+- Distribution percentages are tracked in basis points (1 bp = 0.01%)
+- Total distribution must always equal 100% (10,000 basis points)
+
+### Undistributed Token Handling
+
+- Any tokens not distributed in a cycle are tracked
+- Undistributed tokens are included in the next distribution cycle
+
+### Halving
+
+Adjusts distribution amounts appropriately during halving periods
+
+### Callback Mechanisms
+
+Provides callback function for inter-contract commication. This will notifies relevant components when distribution ratios change.
path: contract/r/gnoswap/emission/README.md
user: login: dongwon8247
body: ```suggestion
# Emission

## Overview

The emission contract manages minting and distributing the `GNS` token.

## Features

### Token Emission and Distribution

- Mints `GNS` tokens on a block generation time basis (initially set [here](https://github.com/gnoswap-labs/gnoswap/blob/main/contract/p/gnoswap/consts/consts.gno#L126), but can be changed by governance)
- Distributes tokens to the set targets
- Tracks undistributed tokens and include it in future distribution cycles

### Distribution Targets

Tokens are distributed to four main targets as follows by default:

- **Liquidity Staker**: 75%
- **DevOps Team**: 20%
- **Community Pool**: 5%
- **Governance Stakers**: 0%

### Distribution Ratio Management

- Governance or admin can adjust token distribution ratio
- Distribution percentages are tracked in basis points (1 bp = 0.01%)
- Total distribution must always equal 100% (10,000 basis points)

### Undistributed Token Handling

- Any tokens not distributed in a cycle are tracked
- Undistributed tokens are included in the next distribution cycle

### Halving

There is a halving mechanism that reduces the issuance amount by half every two years

### Callback Mechanisms

Provides callback function for inter-contract communication. This will notify relevant components when distribution ratios change. Details to be found on our [bridge contract](https://github.com/gnoswap-labs/gnoswap/tree/main/contract/r/gnoswap/bridge#bridge).

For more details about the emission, check out the [GnoSwap docs](https://docs.gnoswap.io/gnoswap-token/emission).
```
created_at: 2025-03-07T12:48:19Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,27 @@
+# GNS Token
+
+The `GNS` token serves as the governance and gnoswap's utility token. The emission system is designed to distribute token gradually over time, with a decreasing inflation rate.
+
+## Token Implementation
+
+- Follows `grc20` token specs
+- Symbol: `GNS`
+- Decimals: 6
+
+## Emission Mechanism
+
+- Block-based token emission with predefined schedule
+- Token emission follows a halving model over a 12 years
+- Each halving period adjusts the amounts of tokens minted per block
+
+## Halving Schedule
+
+- 12 years emission period devided into halving periods
+
+| Years | Description |
+| --- | --- |
+| 1-2 | Full emission rate |
+| 3-4 | 50% of initial emission rate |
+| 5-6 | 25% of initial emission rate |
+| 7-8 | 12.5% of initial emission rate |
+| 9-12 | 6.25% of initial emission rate |
path: contract/r/gnoswap/gns/README.md
user: login: dongwon8247
body: ```suggestion
# GNS Token

The `GNS` token is the governance and main utility token of the GnoSwap protocol

## Token Implementation

- Follows the `grc20` token specs ([grc spec](https://github.com/gnolang/gno/tree/master/examples/gno.land/p/demo/grc))
- Symbol: `GNS`
- Decimals: 6
- Max Supply: 1_000_000_000 (1B)

You can find the detailed tokenomics of GNS [here](https://docs.gnoswap.io/gnoswap-token/whats-gns).

## Emission Mechanism

- Block-based token emission with predefined schedule
- Token emission follows a halving model over 12 years
- Each halving period adjusts the amounts of tokens minted per block

## Halving Schedule

- 12 years emission period devided into halving periods

| Years | Description |
| --- | --- |
| 1-2 | Full emission rate |
| 3-4 | 50% of initial emission rate |
| 5-6 | 25% of initial emission rate |
| 7-8 | 12.5% of initial emission rate |
| 9-12 | 6.25% of initial emission rate |

For details about the emission and distribution of the GNS tokens, refer to our [emission contract](https://github.com/gnoswap-labs/gnoswap/tree/main/contract/r/gnoswap/emission).
```
created_at: 2025-03-07T12:55:05Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,7 @@
+# Launchpad
+
+## Overview
+
+The Launchpad contract enables new projects to raise funds and distribute rewards to users who stake `GNS` tokens.
+
+See more: https://docs.gnoswap.io/core-concepts/launchpad
path: contract/r/gnoswap/launchpad/README.md
user: login: dongwon8247
body: ```suggestion
# Launchpad

The **GnoSwap Launchpad** is a decentralized token launching platform built on **gno.land**, enabling new projects to launch tokens in a **fair, transparent, and trustless** manner.

## Key Concepts

1. "Lossless" Exposure to Early-Stage Projects
GnoSwap Launchpad allows **$GNS holders** to acquire new project tokens **without spending their principal $GNS**. Users lock their **$GNS tokens** in a Launchpad Pool for a fixed period and receive project tokens **pro-rata** while their staked $GNS remains secured in the **xGNS Governance Contract**. After maturity, the same amount of $GNS is returned, ensuring a **"lossless" participation model**.

2. Pool Diversity
Users can choose from **three different pools**, each with varying lock-up periods and reward structures:
- **1 Month** – Short-term commitment, moderate rewards.
- **3 Months** – Balanced duration and rewards.
- **6 Months** – Longer commitment, higher token rewards.

While $GNS remains locked, **project token rewards are liquid** and can be claimed at any time.

3. Yield-Redirection-Based Funding
GnoSwap Launchpad uses a **yield-redirection mechanism** to fund project token rewards.  
- Users' **$GNS deposits** are **staked** in the [xGNS Governance Contract](https://github.com/gnoswap-labs/gnoswap/tree/main/contract/r/gnoswap/gov), earning **Protocol Fee Rewards**.  
- Instead of being returned to users, these **rewards are redirected** to the **Project Owner** in exchange for **newly launching project tokens**.  

For more information about the launchpad feature, refer to: https://docs.gnoswap.io/core-concepts/launchpad
```
created_at: 2025-03-07T13:03:59Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,20 @@
+# Protocol Fee
+
+## Overview
+
+Protocol fee manages how trading fees collected from the protocol are split between the `gov/staker` and the `DevOps` team.
+
+## Fee
+
+### Collection
+
+- Accumulates protocol fees from various operation (swaps, liquidity provision, etc.)
+- Track collected fees by token type
+- Only pool, router, and staker contracts can add fees to the collection
+
+### Distribution
+
+- Distributes collected fees between governance stakers and DevOps
+- Default distribution: 100% to `gov/stakers`, 0% to `DevOps` initially
+- Distribution percentages are configurable
+- Only `gov/staker` contract can trigger fee distribution
path: contract/r/gnoswap/protocol_fee/README.md
user: login: dongwon8247
body: ```suggestion
# Protocol Fee

## Overview

The Protocol Fee contract manages assets collected as protocol fees across the platform and distributes them to xGNS holders via the `gov/staker` contract.

## Fee

### Collection

- Accumulates protocol fees from various operations ([details](https://docs.gnoswap.io/core-concepts/fees#protocol-fees)).
- Tracks collected fees by token type.
- Only the **pool**, **router**, and **staker** contracts can contribute fees to the collection.

### Distribution

- Distributes collected fees between governance stakers and DevOps.
- Default distribution: **100% to `gov/stakers`, 0% to `DevOps`** (initially).
- Distribution percentages are configurable by governance.
- Only the `gov/staker` contract can trigger fee distribution.
```
created_at: 2025-03-07T13:08:10Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,15 @@
+# Referral
+
+The Referral contract implementation for managing referral relationships in the Gnoswap. It provides functionality to register, update, and remove referral relationships between addresses.
+
+## Features
+
+- Register referral relationships between addresses
+- Update existing referral relationships
+- Remove referral relationships
+- Query referral information
+- Rate limiting for operations (24-hour cooldown period)
+
+### Keeper
+
+The underlying implementation that handles the actual storage and validation of referral relationships using an AVL tree data structure.
path: contract/r/gnoswap/referral/README.md
user: login: dongwon8247
body: ```suggestion
# Referral

The Referral contract implementation for managing referral relationships in the GnoSwap. It provides functionality to register, update, and remove referral relationships between addresses.

## Features

- Register referral relationships between addresses
- Update existing referral relationships
- Remove referral relationships
- Query referral information
- Rate limiting for operations (24-hour cooldown period)

### Keeper

The underlying implementation handles the actual storage and validation of referral relationships using an AVL tree data structure.

For the implementation details, refer to the [referral doc.gno](https://github.com/gnoswap-labs/gnoswap/blob/main/contract/r/gnoswap/referral/doc.gno).
```
created_at: 2025-03-07T13:09:54Z
author_association: MEMBER

PR comments:
user: login: sonarqubecloud[bot]
created_at: 2025-03-07T13:25:19Z
body: ## [![Quality Gate Passed](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/checks/QualityGateBadge/qg-passed-20px.png 'Quality Gate Passed')](https://sonarcloud.io/dashboard?id=gnoswap-labs_gnoswap&pullRequest=567) **Quality Gate passed**  
Issues  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 New issues](https://sonarcloud.io/project/issues?id=gnoswap-labs_gnoswap&pullRequest=567&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/accepted-16px.png '') [0 Accepted issues](https://sonarcloud.io/project/issues?id=gnoswap-labs_gnoswap&pullRequest=567&issueStatuses=ACCEPTED)

Measures  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 Security Hotspots](https://sonarcloud.io/project/security_hotspots?id=gnoswap-labs_gnoswap&pullRequest=567&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Coverage on New Code](https://sonarcloud.io/component_measures?id=gnoswap-labs_gnoswap&pullRequest=567&metric=new_coverage&view=list)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Duplication on New Code](https://sonarcloud.io/component_measures?id=gnoswap-labs_gnoswap&pullRequest=567&metric=new_duplicated_lines_density&view=list)  
  
[See analysis details on SonarQube Cloud](https://sonarcloud.io/dashboard?id=gnoswap-labs_gnoswap&pullRequest=567)


author_association: NONE