Add documentation, refactor, and improve protocol logic

This commit adds extensive NatSpec documentation to all core contracts and interfaces, refactors event and error names for consistency, and improves protocol logic in NostalgicController, NostalgicFactory, NostalgicJumpRateModel, and NostalgicPool. It also introduces .solhint config files, updates README with project details, and adds dead shares minting logic to pools. Test files are updated to match new function names and behaviors.

Author: typicalHuman

.solhint.json

@@ -0,0 +1,18 @@
+{
+  "extends": "solhint:recommended",
+  "rules": {
+    "func-visibility": [
+      "error",
+      {
+        "ignoreConstructors": true
+      }
+    ],
+    "max-line-length": [
+      "warn",
+      300
+    ],
+    "import-path-check": "off",
+    "use-natspec": "off",
+    "gas-strict-inequalities": "off"
+  }
+}

.solhintignore

@@ -0,0 +1,3 @@
+test/
+script/
+lib/

README.md

@@ -0,0 +1,74 @@
+# nostalgia
+
+Decentralized lending protocol inspired by Compound v2.
+It allows users to supply and borrow assets through smart contracts, earning interest algorithmically based on market dynamics.
+Motivation for this: **"I Don't Understand Anything I Can't Build"**.
+
+![art](./assets/art.gif)
+
+## 🧱 Overview
+
+- **`NostalgicController.sol`** – Core risk management and market control logic.
+- **`NostalgicFactory.sol`** – Responsible for deploying and managing new pool instances.
+- **`NostalgicJumpRateModel.sol`** – Implements an interest rate model with a jump multiplier, adjusting rates dynamically based on utilization.
+- **`NostalgicPool.sol`** – Core pool contract for supplying and borrowing assets.
+
+## 🧪 Testing
+
+The project uses **[Foundry](https://book.getfoundry.sh/)** for testing and development.
+Tests are located under the `test/` directory, with mocks and unit tests for each module.
+
+```
+╭--------------------------------+-------------------+-------------------+-----------------+-----------------╮
+| File                           | % Lines           | % Statements      | % Branches      | % Funcs         |
++============================================================================================================+
+| src/NostalgicController.sol    | 100.00% (80/80)   | 100.00% (86/86)   | 100.00% (30/30) | 100.00% (16/16) |
+|--------------------------------+-------------------+-------------------+-----------------+-----------------|
+| src/NostalgicFactory.sol       | 100.00% (23/23)   | 100.00% (21/21)   | 100.00% (2/2)   | 100.00% (5/5)   |
+|--------------------------------+-------------------+-------------------+-----------------+-----------------|
+| src/NostalgicJumpRateModel.sol | 100.00% (12/12)   | 100.00% (13/13)   | 100.00% (2/2)   | 100.00% (2/2)   |
+|--------------------------------+-------------------+-------------------+-----------------+-----------------|
+| src/NostalgicPool.sol          | 100.00% (145/145) | 100.00% (145/145) | 100.00% (33/33) | 100.00% (28/28) |
+|--------------------------------+-------------------+-------------------+-----------------+-----------------|
+| Total                          | 100.00% (260/260) | 100.00% (265/265) | 100.00% (67/67) | 100.00% (51/51) |
+╰--------------------------------+-------------------+-------------------+-----------------+-----------------╯
+```
+
+Run the full test suite:
+
+```bash
+forge test
+```
+
+For more detailed output:
+
+```bash
+forge test -vvv
+```
+
+## 🧰 Project Structure
+
+```
+src/
+ ├─ interfaces/
+ │   ├─ NostalgicController.sol
+ │   ├─ NostalgicFactory.sol
+ │   ├─ NostalgicJumpRateModel.sol
+ └─  └─ NostalgicPool.sol
+```
+
+## ⚙️ Setup
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/typicalHuman/nostalgia.git
+cd nostalgia
+forge install
+```
+
+Build the contracts:
+
+```bash
+forge build
+```

assets/art.gif

@@ -4,8 +4,8 @@ pragma solidity ^0.8.28;
 import {INostalgicPool} from "./interfaces/INostalgicPool.sol";
 import {INostalgicController} from "./interfaces/INostalgicController.sol";
 import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
 import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
-import {console} from "forge-std/console.sol";
 
 //  /$$   /$$                       /$$               /$$           /$$            /$$$$$$                        /$$                         /$$ /$$
 // | $$$ | $$                      | $$              | $$          |__/           /$$__  $$                      | $$                        | $$| $$
@@ -18,23 +18,44 @@ import {console} from "forge-std/console.sol";
 //                                                        /$$  \ $$
 //                                                       |  $$$$$$/
 //                                                        \______/
-//
-contract NostalgicController is AccessControl, INostalgicController {
+
+/// @title Nostalgic Controller
+/// @notice Manages user interactions with Nostalgic Pools
+/// @author typicalHuman
+contract NostalgicController is
+    AccessControl,
+    ReentrancyGuard,
+    INostalgicController
+{
     using Math for uint256;
 
     uint256 internal constant SCALING_FACTOR = 1e18;
 
+    /// @notice Liquidation incentive for liquidators
+    uint256 public constant LIQUIDATION_INCENTIVE = 0.04e18; // 4%
+
+    /// @notice Protocol liquidation fee
+    uint256 public constant PROTOCOL_LIQUIDATION_FEE = 0.01e18; // 1%
+
+    /// @notice Address of the Nostalgic factory contract
+    address public factory;
+
+    /// @notice Mapping of existing pool addresses
     mapping(INostalgicPool pool => bool exists) public existingPools;
+
+    /// @notice Mapping of user addresses to their entered pool addresses
     mapping(address user => INostalgicPool[] pools) public userEnteredMarkets;
+
+    /// @notice Mapping of user addresses to their interaction status with each pool
     mapping(address user => mapping(INostalgicPool pool => bool hasInteracted))
         public userMarketEntries;
-    mapping(address asset => uint256 collateralFactor) public collateralFactors;
 
-    address public factory;
-
-    uint256 public liquidationIncentive = 0.04e18; // 4%
-    uint256 public protocolLiquidationFee = 0.01e18; // 1%
+    /// @notice Mapping of asset addresses to their collateral factors
+    mapping(address asset => uint256 collateralFactor) public collateralFactors;
 
+    /// @notice Constructor for the NostalgicController contract
+    /// @param initialAdmin The address of the initial admin
+    /// @param _factory The address of the Nostalgic factory contract
     constructor(address initialAdmin, address _factory) {
         require(
             initialAdmin != address(0) && _factory != address(0),
@@ -44,11 +65,14 @@ contract NostalgicController is AccessControl, INostalgicController {
         _grantRole(DEFAULT_ADMIN_ROLE, initialAdmin);
     }
 
-    modifier onlyOwnerOrFactory() {
-        _onlyOwnerOrFactory();
+    /// @notice Modifier to restrict access to the admin or factory
+    modifier onlyAdminOrFactory() {
+        _onlyAdminOrFactory();
         _;
     }
 
+    /// @notice Updates the address of the Nostalgic factory contract
+    /// @param newFactory The address of the new Nostalgic factory contract
     function updateFactory(
         address newFactory
     ) public onlyRole(DEFAULT_ADMIN_ROLE) {
@@ -57,29 +81,36 @@ contract NostalgicController is AccessControl, INostalgicController {
         emit FactoryUpdate(newFactory);
     }
 
+    /// @inheritdoc INostalgicController
     function isHealthy(address user) public view returns (bool) {
         (uint256 totalUsdCollateral, uint256 totalUsdBorrow) = userPosition(
             user
         );
         return totalUsdCollateral >= totalUsdBorrow;
     }
 
+    /// @inheritdoc INostalgicController
     function userPosition(
         address user
     ) public view returns (uint256 totalUsdCollateral, uint256 totalUsdBorrow) {
         INostalgicPool[] memory investedPools = userEnteredMarkets[user];
-        for (uint i = 0; i < investedPools.length; i++) {
-            uint256 userCollateral = investedPools[i].getTokenValueInUSD(
-                investedPools[i].userLends(user)
+        for (uint256 i = 0; i < investedPools.length; ) {
+            INostalgicPool pool = investedPools[i];
+
+            uint256 userCollateral = pool.getTokenValueInUSD(
+                pool.userLends(user)
             );
-            totalUsdBorrow += investedPools[i].getTokenValueInUSD(
-                investedPools[i].scaledBorrowPosition(user)
+            totalUsdBorrow += pool.getTokenValueInUSD(
+                pool.scaledBorrowPosition(user)
             );
 
-            totalUsdCollateral += getUsdValue(investedPools[i], userCollateral);
+            totalUsdCollateral += getUsdValue(pool, userCollateral);
+            unchecked {
+                ++i;
+            }
         }
     }
-
+    /// @inheritdoc INostalgicController
     function canBorrow(
         INostalgicPool pool,
         address user,
@@ -95,12 +126,13 @@ contract NostalgicController is AccessControl, INostalgicController {
         return totalUsdCollateral > totalUsdBorrow;
     }
 
+    /// @inheritdoc INostalgicController
     function liquidateBorrower(
         address borrower,
         address liquidator,
         uint256 repaidAmount,
         INostalgicPool collateralPool
-    ) external {
+    ) external nonReentrant {
         require(
             existingPools[INostalgicPool(msg.sender)] &&
                 existingPools[collateralPool],
@@ -113,9 +145,9 @@ contract NostalgicController is AccessControl, INostalgicController {
             repaidAmountUsd
         );
         uint256 liquidatorIncentive = (repaidInCollateralToken *
-            liquidationIncentive) / SCALING_FACTOR;
+            LIQUIDATION_INCENTIVE) / SCALING_FACTOR;
         uint256 protocolReward = (repaidInCollateralToken *
-            protocolLiquidationFee) / SCALING_FACTOR;
+            PROTOCOL_LIQUIDATION_FEE) / SCALING_FACTOR;
         uint256 liquidatorReward = liquidatorIncentive +
             repaidInCollateralToken;
         require(
@@ -131,11 +163,12 @@ contract NostalgicController is AccessControl, INostalgicController {
         );
     }
 
+    /// @inheritdoc INostalgicController
     function interactWithPool(address user) external {
         require(existingPools[INostalgicPool(msg.sender)], PoolNotFound());
         uint256 lends = INostalgicPool(msg.sender).userLends(user);
         uint256 borrows = INostalgicPool(msg.sender).userBorrows(user);
-        bool toAdd = lends + borrows > 0 ? true : false;
+        bool toAdd = lends + borrows > 0;
         if (toAdd) {
             if (userMarketEntries[user][INostalgicPool(msg.sender)]) return;
             userMarketEntries[user][INostalgicPool(msg.sender)] = true;
@@ -147,83 +180,113 @@ contract NostalgicController is AccessControl, INostalgicController {
         _removePool(user, INostalgicPool(msg.sender));
     }
 
-    function addPool(INostalgicPool pool) external onlyOwnerOrFactory {
+    /// @notice Adds a new Nostalgic pool
+    /// @param pool The address of the Nostalgic pool to add
+    function addPool(INostalgicPool pool) external onlyAdminOrFactory {
         existingPools[pool] = true;
 
-        emit PoolAdded(pool);
+        emit PoolAdd(pool);
     }
 
+    /// @notice Removes an existing Nostalgic pool
+    /// @param pool The address of the Nostalgic pool to remove
     function removePool(
         INostalgicPool pool
     ) external onlyRole(DEFAULT_ADMIN_ROLE) {
         require(pool.totalLended() == 0, PoolNotEmpty());
         existingPools[pool] = false;
-        emit PoolRemoved(pool);
+        emit PoolRemove(pool);
     }
+
+    /// @notice Adds a new asset to the collateral manager
+    /// @param asset The address of the asset to add
+    /// @param collateralFactor The collateral factor for the asset
     function addAsset(
         address asset,
         uint256 collateralFactor
-    ) external onlyOwnerOrFactory {
+    ) external onlyAdminOrFactory {
         require(collateralFactors[asset] == 0, AssetAlreadyAdded());
         require(
             collateralFactor <=
-                SCALING_FACTOR - protocolLiquidationFee - liquidationIncentive,
+                SCALING_FACTOR -
+                    PROTOCOL_LIQUIDATION_FEE -
+                    LIQUIDATION_INCENTIVE,
             InvalidCollateralFactor()
         );
         collateralFactors[asset] = collateralFactor;
 
-        emit AssetAdded(asset, collateralFactor);
+        emit AssetAdd(asset, collateralFactor);
     }
 
-    function update(
+    /// @notice Updates the collateral factor for an existing asset
+    /// @param asset The address of the asset to update
+    /// @param collateralFactor The new collateral factor for the asset
+    function updateCollateralFactor(
         address asset,
         uint256 collateralFactor
     ) external onlyRole(DEFAULT_ADMIN_ROLE) {
         require(collateralFactors[asset] != 0, AssetNotAdded());
         require(
             collateralFactor <=
-                SCALING_FACTOR - protocolLiquidationFee - liquidationIncentive,
+                SCALING_FACTOR -
+                    PROTOCOL_LIQUIDATION_FEE -
+                    LIQUIDATION_INCENTIVE,
             InvalidCollateralFactor()
         );
         collateralFactors[asset] = collateralFactor;
 
-        emit CollateralFactorUpdated(asset, collateralFactor);
+        emit CollateralFactorUpdate(asset, collateralFactor);
     }
 
+    /// @notice Removes an existing asset from the collateral manager
+    /// @param asset The address of the asset to remove
     function removeAsset(address asset) external onlyRole(DEFAULT_ADMIN_ROLE) {
         require(collateralFactors[asset] != 0, AssetNotAdded());
 
         collateralFactors[asset] = 0;
-        emit AssetRemoved(asset);
+        emit AssetRemove(asset);
     }
 
+    /// @notice Gets the USD value of a given amount of an asset in a Nostalgic pool
+    /// @param pool The Nostalgic pool to get the USD value from
+    /// @param amount The amount of the asset to convert to USD
     function getUsdValue(
         INostalgicPool pool,
         uint256 amount
     ) public view returns (uint256) {
         return amount.mulDiv(collateralFactors[pool.asset()], SCALING_FACTOR);
     }
 
-    function _onlyOwnerOrFactory() internal view {
+    /// @notice Checks if the caller is the admin or the factory
+    function _onlyAdminOrFactory() internal view {
         require(
             hasRole(DEFAULT_ADMIN_ROLE, msg.sender) || msg.sender == factory,
             InvalidCaller()
         );
     }
 
+    /// @notice Removes a Nostalgic pool from a user's entered markets
+    /// @param user The address of the user
+    /// @param pool The Nostalgic pool to remove
     function _removePool(address user, INostalgicPool pool) internal {
-        uint length = userEnteredMarkets[user].length;
-        for (uint i = 0; i < length; i++) {
+        uint256 length = userEnteredMarkets[user].length;
+        for (uint256 i = 0; i < length; ) {
             if (userEnteredMarkets[user][i] == pool) {
                 // Shift elements left
-                for (uint j = i; j < length - 1; j++) {
+                for (uint256 j = i; j < length - 1; ) {
                     userEnteredMarkets[user][j] = userEnteredMarkets[user][
                         j + 1
                     ];
+                    unchecked {
+                        ++j;
+                    }
                 }
                 userEnteredMarkets[user].pop(); // remove last
                 break;
             }
+            unchecked {
+                ++i;
+            }
         }
     }
 }