WIP snapshot: refactored core, unit tests, deploy script, and CLAUDE.md

- Restructured src into core/, interfaces/, tokens/ layers
- Added BaseERC20, Constants, Errors, Modifiers contracts
- Added CodesenSysToken with owner-gated mint and open burn
- Added unit tests for Transfer, Allowance, MintBurn with BaseTest setup
- Added Deploy script and CLAUDE.md
- Invariant tests and fuzz suite pending completion

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: CodesenSys

CLAUDE.md

@@ -1,16 +1,21 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.4;
-import {Script} from "forge-std/Script.sol";
-import {CodesenSysToken} from  "../src/tokens/CodesenSysToken.sol"; 
 
+import {Script, console} from "forge-std/Script.sol";
+import {CodesenSysToken} from "../src/tokens/CodesenSysToken.sol";
+import {Constants} from "../src/core/Constants.sol";
 
 contract Deploy is Script {
-    function run() external {
-        // uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
-        // vm.startBroadcast(vm.envUint("DEPLOYER_PRIVATE_KEY"));
-        vm.startBroadcast();
-        new CodesenSysToken(msg.sender, 1_000_000e18);
+    function run() external returns (CodesenSysToken token) {
+        uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
+        address owner = vm.envAddress("OWNER_ADDRESS");
+
+        vm.startBroadcast(deployerPrivateKey);
+        token = new CodesenSysToken(owner, Constants.INITIAL_SUPPLY);
         vm.stopBroadcast();
+
+        console.log("Token deployed at :", address(token));
+        console.log("Owner             :", owner);
+        console.log("Initial supply    :", Constants.INITIAL_SUPPLY);
     }
 }
-

script/Deploy.s.sol

@@ -1,2 +1,14 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.4;
+library Constants {
+
+    // Token Metadata
+    string  internal constant TOKEN_NAME   = "CodesenSys Token";
+    string  internal constant TOKEN_SYMBOL = "CSS";
+    uint8   internal constant DECIMALS     = 18;
+    uint256 private constant _SCALAR = 10 ** uint256(DECIMALS);
+    uint256 internal constant INITIAL_SUPPLY = 1_000_000 * _SCALAR;
+    
+    /// @dev Hard cap of 1,000,000,000 CSS (1 Billion).
+    uint256 internal constant MAX_SUPPLY = 1_000_000_000 * _SCALAR;
+}

src/core/Constants.sol

@@ -1,6 +1,21 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.4;
+
+/// @title  Errors
+/// @author CodesenSys
+/// @notice Centralised custom errors for the CodesenSys protocol.
+///         Custom errors save gas vs string reverts and give callers
+///         a typed selector to match against in tests.
 library Errors {
+    /// @dev Thrown when a zero address is supplied where one is not allowed.
     error ZeroAddress();
+
+    /// @dev Thrown when a zero amount is supplied where one is not allowed.
     error ZeroAmount();
+
+    /// @dev Thrown when msg.sender is not the authorised OWNER.
+    error NotAuthorized();
+
+    /// @dev Thrown when a mint would push totalSupply past MAX_SUPPLY.
+    error ExceedsCap();
 }

src/core/Errors.sol

@@ -1,2 +1,29 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.4;
+pragma solidity ^0.8.4;
+
+import {Errors} from "./Errors.sol";
+
+/// @title  Modifiers
+/// @author CodesenSys
+/// @notice Abstract contract that owns the OWNER immutable and exposes the
+///         onlyOwner modifier. Inheriting contracts pass the owner address
+///         through the constructor — no storage slot is used (immutable).
+abstract contract Modifiers {
+
+    // State
+    address public immutable owner;
+
+    // Constructor
+    constructor(address _owner) {
+        if (_owner == address(0)) revert Errors.ZeroAddress();
+        owner = _owner;
+    }
+
+    // Modifiers
+    /// @dev Reverts with a custom error when the caller is not the OWNER.
+    ///      Custom errors are cheaper than string reverts (less calldata).
+    modifier onlyOwner() {
+        if (msg.sender != owner) revert Errors.NotAuthorized();
+        _;
+    }
+}

src/core/Modifiers.sol

@@ -1,2 +1,72 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.4;
+pragma solidity ^0.8.4;
+
+/// @title  IERC20
+/// @author CodesenSys
+/// @notice Full EIP-20 interface plus the mint/burn extensions
+///         specific to CodesenSysToken.
+///         Solady's ERC20 already satisfies the core surface —
+///         this interface lets external contracts and off-chain
+///         tooling reference the complete ABI from a single file.
+interface IERC20 {
+
+    // =========================================================================
+    // Events  (EIP-20 required)
+    // =========================================================================
+
+    /// @notice Emitted on every successful transfer, including mints (from == 0)
+    ///         and burns (to == 0).
+    event Transfer(address indexed from, address indexed to, uint256 value);
+
+    /// @notice Emitted when an owner updates a spender's allowance via approve()
+    ///         or when a transferFrom() reduces it.
+    event Approval(address indexed owner, address indexed spender, uint256 value);
+
+    // =========================================================================
+    // EIP-20 Core
+    // =========================================================================
+
+    /// @notice Human-readable name of the token (e.g. "CodesenSys Token").
+    function name() external view returns (string memory);
+
+    /// @notice Short ticker symbol (e.g. "CSS").
+    function symbol() external view returns (string memory);
+
+    /// @notice Number of decimal places used to represent token amounts.
+    ///         CSS uses 18, matching Ether convention.
+    function decimals() external view returns (uint8);
+
+    /// @notice Total tokens currently in existence (minted minus burned).
+    function totalSupply() external view returns (uint256);
+
+    /// @notice Token balance held by `account`.
+    function balanceOf(address account) external view returns (uint256);
+
+    /// @notice Transfer `amount` from the caller to `to`.
+    /// @return success True on success; implementations MUST revert on failure.
+    function transfer(address to, uint256 amount) external returns (bool success);
+
+    /// @notice Remaining tokens that `spender` is allowed to move on behalf of `owner`.
+    function allowance(address owner, address spender) external view returns (uint256);
+
+    /// @notice Approve `spender` to transfer up to `amount` from the caller's balance.
+    /// @dev    Setting to zero and then to the new value is the safe pattern for
+    ///         non-zero → non-zero updates on ERC-20 contracts that track old allowances.
+    /// @return success True on success.
+    function approve(address spender, uint256 amount) external returns (bool success);
+
+    /// @notice Move `amount` from `from` to `to` using the caller's allowance.
+    /// @return success True on success.
+    function transferFrom(address from, address to, uint256 amount) external returns (bool success);
+
+    // =========================================================================
+    // Extensions — CodesenSysToken specific
+    // =========================================================================
+
+    /// @notice Mint `amount` new tokens to `to`. Restricted to OWNER.
+    /// @dev    Reverts with Errors.ExceedsCap if totalSupply + amount > MAX_SUPPLY.
+    function mint(address to, uint256 amount) external;
+
+    /// @notice Burn `amount` tokens from the caller's own balance.
+    function burn(uint256 amount) external;
+}

src/interfaces/IERC20.sol

@@ -1,28 +1,48 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.4;
+
 import {BaseERC20} from "../core/BaseERC20.sol";
+import {Modifiers} from "../core/Modifiers.sol";
+import {Constants} from "../core/Constants.sol";
+import {Errors} from "../core/Errors.sol";
+
+/// @title  CodesenSysToken
+/// @author CodesenSys
+/// @notice ERC-20 token with owner-gated minting, open burning, and a hard 1 billion token supply cap.
+contract CodesenSysToken is BaseERC20, Modifiers {
 
-contract CodesenSysToken is BaseERC20 {
-    address public immutable OWNER;
+    // Constructor
 
-    constructor(address _owner, uint256 initialSupply) {
-        OWNER = _owner;
+    /// @param _owner        Receives the initial supply and mint rights.
+    /// @param initialSupply Tokens minted at deployment (use Constants.INITIAL_SUPPLY).
+    constructor(address _owner, uint256 initialSupply)
+        Modifiers(_owner)
+    {
         _mintInternal(_owner, initialSupply);
     }
 
+    // Metadata
+
     function name() public pure override returns (string memory) {
-        return "CodesenSys Token";
+        return Constants.TOKEN_NAME;
     }
 
     function symbol() public pure override returns (string memory) {
-        return "CSS";
+        return Constants.TOKEN_SYMBOL;
     }
 
-    function mint(address to, uint256 amount) external {
-        if (msg.sender != OWNER) revert("NOT_AUTHORIZED");
+    // Core logic
+
+    /// @notice Mint new tokens. Restricted to OWNER; enforces the 1B hard cap.
+    /// @param to     Recipient — must not be the zero address (checked in BaseERC20).
+    /// @param amount Token quantity in wei — must be non-zero (checked in BaseERC20).
+    function mint(address to, uint256 amount) external onlyOwner {
+        if (totalSupply() + amount > Constants.MAX_SUPPLY) revert Errors.ExceedsCap();
         _mintInternal(to, amount);
     }
 
+    /// @notice Burn tokens from the caller's own balance.
+    /// @param amount Token quantity in wei — must be non-zero (checked in BaseERC20).
     function burn(uint256 amount) external {
         _burnInternal(msg.sender, amount);
     }

src/tokens/CodesenSysToken.sol

@@ -1,2 +1,41 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.4;
+pragma solidity ^0.8.24;
+
+import {Test} from "forge-std/Test.sol";
+import {CodesenSysToken} from "../../src/tokens/CodesenSysToken.sol";
+
+ contract CodesenSysTokenInvariant is Test {
+     CodesenSysToken public token;
+     address public owner = 0x8C02Cadc32805F85037266206ce4FF347148bb98;
+    
+     function setUp() public {
+         token = new CodesenSysToken(owner, 1_000_000e18);
+     }
+    
+     function invariant_TotalSupplyEqualsBalances() public view {
+         // This would need a handler to track all addresses
+         // For now, simplified version
+         assertEq(
+             token.totalSupply(),
+             token.balanceOf(owner) // + all other balances
+         );
+     }
+    
+     // INVARIANT 2: Total supply never goes below zero
+     function invariant_TotalSupplyNeverNegative() public view {
+         assertGe(token.totalSupply(), 0);
+     }
+    
+     // INVARIANT 3: Owner balance never exceeds total supply
+     function invariant_OwnerBalanceNeverExceedsTotalSupply() public view {
+         assertLe(token.balanceOf(owner), token.totalSupply());
+     }
+    
+     // INVARIANT 4: Any user balance never exceeds total supply
+     function invariant_NoBalanceExceedsTotalSupply() public view {
+         // Would need handler to track all users
+         assertLe(token.balanceOf(owner), token.totalSupply());
+     }
+ }
+
+