chore: fix documentation across contracts (#803)

* chore: fix documentation issues across contracts

- Convert all-caps comments to lowercase following Go conventions
- Fix halving period documentation (4 years → 2 years)
- Update block-based references to timestamp-based
- Add address validation to SetRoleAddresses
- Apply Go convention for function documentation (Parameters/Returns format)
- Fix typo: 'devided' → 'divided'

* chore: improve access and emission documentation

- Fix misleading comments in access contract
- Simplify verbose function documentation
- Update README to match actual implementation
- Remove redundant parameter descriptions
- Make comments concise and accurate

* chore: standardize documentation across all contracts

- Apply consistent Go comment conventions
- Remove verbose AI-style parameter lists
- Keep critical GnoSwap-specific logic explanations
- Fix incorrect documentation that didn't match implementation
- Simplify README files while preserving technical accuracy
- Make documentation concise and human-readable

* chore: add governance parameter documentation

- Add 'Configurable Parameters' sections to all relevant README files
- Add inline comments for governance-modifiable variables
- Document default values for all configurable parameters
- Include parameters for: emission distribution, fees, pool tiers, governance settings
- Remove separation between admin/governance access in documentation

* chore: remove test.sh

* fix

* fix

* fix

* add more details in readme and key functions

* fix

* fix

* final readme edit

* Update README.md

Signed-off-by: Dongwon <[email protected]>

* fix: tests

* chore: update tree

---------

Signed-off-by: Dongwon <[email protected]>
Signed-off-by: Lee ByeongJun <[email protected]>
Co-authored-by: Lee ByeongJun <[email protected]>
Co-authored-by: jinoosss <[email protected]>

Author: 3 people

README.md

@@ -1,226 +1,133 @@
 # GnoSwap Contracts
 
-This repository contains smart contracts (realms) for GnoSwap.
+Smart contracts for GnoSwap AMM DEX on Gno.land.
 
-## Index
-
-- [Setting Up and Testing GnoSwap Contracts](#setting-up-and-testing-gnoswap-contracts)
-  - [Prerequisites](#prerequisites)
-  - [Setting Up GnoSwap Contracts](#setting-up-gnoswap-contracts)
-  - [Running Tests](#running-tests)
-- [Realms](#realms)
-  - [Core Realms Deployed on Testnet5](#core-realms-deployed-on-testnet5)
-
-
-## Setting Up and Testing GnoSwap Contracts
-
-There are two ways to set up GnoSwap contracts: using the provided setup script or manually following the steps below.
-
-### Prerequisites
+## Prerequisites
 
 - GNU Make 3.81 or higher
 - Latest version of [gno.land](https://github.com/gnolang/gno)
 - Python 3.12 or higher
 
-### Using the Setup Script
-
-> Note: If you're using the script, you don't need to manually perform the steps listed in the next section.
-
-For convenience, we provide a Python script that automates the setup process. This script can clone the repository, copy contracts, and move test files as needed.
-
-- To set up in your home directory without cloning the repository:
+## Setup
 
-  ```bash
-  python3 setup.py
-  ```
-
-- To set up in a specific directory without cloning:
-
-  ```bash
-  python3 setup.py -w /path/to/workdir
-  ```
-
-- To clone the repository and set up in your home directory:
+```bash
+# Quick setup in home directory
+python3 setup.py
 
-  ```bash
-  python3 setup.py -c
-  ```
+# Setup in custom directory
+python3 setup.py -w /path/to/workdir
 
-- To clone the repository and set up in a specific directory:
+# Clone repository and setup
+python3 setup.py -c
 
-  ```bash
-  python3 setup.py -w /path/to/workdir -c
-  ```
+# Clone to custom directory
+python3 setup.py -w /path/to/workdir -c
+```
 
 Options:
 
-- `-w` or `--workdir`: Specify the working directory (default is your home directory)
-- `-c` or `--clone`: Clone the gnoswap repository before setting up
-
-The script will perform all necessary steps to set up the GnoSwap contracts in the specified directory.
-
-<details>
-<summary><h3>Setting Up GnoSwap Contracts Manually</h3></summary>
-
-> Important: This manual setup method is not recommended and should only be used as a last resort. If the setup script is not working properly, please create an issue in the repository.
-
-This section guides you through the process of setting up GnoSwap contracts. The process involves three main steps: cloning the `gnoswap` repository, copying the contracts to the `gno` directory, and moving test cases to their respective directories.
-
-1. Clone the repository:
-
-   ```bash
-   cd $WORKDIR
-   git clone https://github.com/gnoswap-labs/gnoswap.git
-   cd gnoswap
-   ```
-
-2. Understand the directory structure pattern:
-
-   ```tree
-   contract/
-   ├── p/  # Packages directory
-   │   └── gnoswap/
-   │       ├── gnsmath/
-   │       └── ...
-   └── r/  # Realms directory
-       └── gnoswap/
-           ├── common/
-           ├── pool/
-           └── ...
-   ```
-
-3. Create the base directories:
-
-   ```bash
-   # Create directories for packages and realms
-   mkdir -p $WORKDIR/gno/examples/gno.land/p/gnoswap
-   mkdir -p $WORKDIR/gno/examples/gno.land/r/gnoswap/v1
-   ```
-
-4. Copy files following these patterns:
-
-   For packages:
-
-   ```bash
-   # Pattern:
-   cp -R contract/p/gnoswap/<package_name> $WORKDIR/gno/examples/gno.land/p/gnoswap/
-
-   # Examples:
-   cp -R contract/p/gnoswap/consts $WORKDIR/gno/examples/gno.land/p/gnoswap/
-   cp -R contract/p/gnoswap/gnsmath $WORKDIR/gno/examples/gno.land/p/gnoswap/
-   ```
-
-   For realm modules:
-
-   ```bash
-   # Pattern:
-   cp -R contract/r/gnoswap/<module_name> $WORKDIR/gno/examples/gno.land/r/gnoswap/v1/
+- `-w` or `--workdir`: Specify working directory (default: home directory)
+- `-c` or `--clone`: Clone gnoswap repository before setup
 
-   # Examples:
-   cp -R contract/r/gnoswap/pool $WORKDIR/gno/examples/gno.land/r/gnoswap/v1/
-   cp -R contract/r/gnoswap/router $WORKDIR/gno/examples/gno.land/r/gnoswap/v1/
-   ```
+If the setup script fails, you can manually copy contracts:
 
-   For test tokens:
+1. Clone repository:
 
-   ```bash
-   # Pattern:
-   cp -R contract/r/gnoswap/test_token/<token_name> $WORKDIR/gno/examples/gno.land/r/
-
-   # Example:
-   cp -R contract/r/gnoswap/test_token/usdc $WORKDIR/gno/examples/gno.land/r/
-   ```
-
-5. Verify the setup:
-
-   ```bash
-   cd $WORKDIR/gno/examples
-   gno test -root-dir $WORKDIR/gno -v=false ./gno.land/r/gnoswap/v1/pool
-   ```
-
-> Note: The setup maintains the original directory structure, including test files which are now part of their respective packages.
-
-</details>
-
-### Directory Structure Overview
-
-Key directories and their purposes:
-
-- `p/gnoswap/`: Core packages including math utilities and constants
-- `r/gnoswap/v1/`: Protocol realms (pool, router, position, etc.)
-- `r/gnoswap/test_token/`: Test tokens for development
-
-Once you understand these patterns, you can copy any additional modules using the same structure.
+```bash
+git clone https://github.com/gnoswap-labs/gnoswap.git
+```
 
-### Running Tests
+2. Copy packages:
 
-While it's possible to run tests in the cloned `gno` directory (where the above setup process was completed), it's recommended to run them in the `gnoswap` directory to avoid confusion due to the large number of changed files.
+```bash
+mkdir -p $WORKDIR/gno/examples/gno.land/p/gnoswap
+cp -R contract/p/gnoswap/* $WORKDIR/gno/examples/gno.land/p/gnoswap/
+```
 
-First, navigate to the `gno/examples` directory:
+3. Copy realms:
 
 ```bash
-cd $WORKDIR/gno/examples
+mkdir -p $WORKDIR/gno/examples/gno.land/r/gnoswap/v1
+cp -R contract/r/gnoswap/* $WORKDIR/gno/examples/gno.land/r/gnoswap/v1/
 ```
 
-Next, move to the Realm directory you want to test (such as `pool`, `staker`, etc.), then run the tests using the `gno test` command:
+4. Copy test tokens:
 
 ```bash
-gno test -root-dir $WORKDIR/gno -v=false ./gno.land/r/gnoswap/v1/pool
+cp -R contract/r/gnoswap/test_token/* $WORKDIR/gno/examples/gno.land/r/
 ```
 
-## Realms
+## Directory Structure
 
-### Core Realms Deployed on Testnet5
-
-- pool: [gno.land/r/gnoswap/v1/pool](https://gnoscan.io/realms/details?path=gno.land/r/gnoswap/v1/pool)
-- position: [gno.land/r/gnoswap/v1/position](https://gnoscan.io/realms/details?path=gno.land/r/gnoswap/v1/position)
-- router: [gno.land/r/gnoswap/v1/router](https://gnoscan.io/realms/details?path=gno.land/r/gnoswap/v1/router)
-- staker: [gno.land/r/gnoswap/v1/staker](https://gnoscan.io/realms/details?path=gno.land/r/gnoswap/v1/staker)
+```
+gnoswap/
+├── contract/                       # Smart contracts
+│   ├── p/                          # Packages (libraries)
+│   │   └── gnoswap/
+│   │       ├── gnsmath/            # AMM math utilities
+│   │       ├── int256/             # 256-bit signed integers
+│   │       ├── uint256/            # 256-bit unsigned integers
+│   │       ├── rbac/               # Role-based access control
+│   │       └── consts/             # Protocol constants
+│   │
+│   └── r/                          # Realms (contracts)
+│       └── gnoswap/
+│           ├── v1/                 # Protocol v1 contracts
+│           │   ├── pool/           # Concentrated liquidity pools
+│           │   ├── position/       # LP position NFTs
+│           │   ├── router/         # Swap routing
+│           │   ├── staker/         # Liquidity mining
+│           │   ├── gov/            # Governance
+│           │   ├── launchpad/      # Token distribution
+│           │   ├── protocol_fee/   # Fee management
+│           │   └── community_pool/ # Treasury
+│           │
+│           ├── access/             # Access control
+│           ├── emission/           # GNS emission
+│           ├── gns/                # GNS token
+│           ├── halt/               # Emergency pause
+│           ├── rbac/               # RBAC realm
+│           ├── referral/           # Referral system
+│           └── test_token/         # Test tokens
+│
+├── tests/                          # Test suites
+│   ├── scenario/                   # Scenario-based tests
+│   ├── integration/                # Integration tests
+│   └── deploy/                     # Deployment scripts
+│
+└── scripts/                        # Utility scripts
+```
 
-## Development Environment Setup
+## Testing
 
-### Using Docker (Recommended)
+### Run All Tests
 
-1. Build the Docker image:
 ```bash
-make docker-build
+make test
 ```
 
-2. Start the container:
-```bash
-make docker-up
-```
+### Run Specific Scenario Tests
 
-3. Access the container shell:
 ```bash
-make docker-shell
+make test-folder FOLDER=tests/scenario/pool
+make test-folder FOLDER=tests/scenario/router
 ```
 
-4. View logs:
-```bash
-make docker-logs
-```
+### Run Integration Tests
 
-5. Stop the container:
 ```bash
-make docker-down
+cd $WORKDIR/gno/examples
+gno test -root-dir $WORKDIR/gno -v=false ./gno.land/r/gnoswap/v1/pool
 ```
 
-### Manual Setup
+## Security
 
-If you prefer to set up the environment manually:
+GnoSwap implements multiple layers of security across all contracts. For security concerns or vulnerability reports, see [SECURITY.md](SECURITY.md).
 
-1. Install Python 3.11 or later
-2. Install uv package manager:
-```bash
-pip install uv
-```
+## License
 
-3. Create a virtual environment and install dependencies:
-```bash
-uv venv
-source .venv/bin/activate  # On Unix/macOS
-# or
-.venv\Scripts\activate  # On Windows
-uv pip install -r requirements.txt
-```
+Licensed under the GNU Affero General Public License v3.0. See [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please follow existing patterns, include tests, and maintain documentation.