readme updated

Author: CodesenSys

README.md

@@ -1,10 +1,10 @@
-<<<<<<< HEAD
 # CodesenSys ERC20 Implementation (Foundry | Solady)
 
-A production-grade, security-first ERC20 token implementation built by **CodesenSys** using **Foundry**.  
-This repository is not a toy example. It is designed as a **reference-grade, extensible, auditable ERC20 codebase** suitable for real-world deployments.
+A production-grade, security-first ERC20 token implementation built by **CodesenSys** using **Foundry** and **Solady**.  
+It is designed as a **reference-grade, extensible, auditable ERC20 codebase** suitable for real-world deployments.
 
 The focus is on:
+
 - Correctness
 - Security
 - Gas efficiency
@@ -16,24 +16,33 @@ The focus is on:
 
 ## Why This Repository Exists
 
-Most ERC20 examples stop at “it compiles and transfers tokens”.
+Most ERC20 examples stop at "it compiles and transfers tokens".
 
 This implementation goes further:
 
 - Models **real production concerns**
 - Enforces **strict invariants**
-- Uses **Foundry’s testing, fuzzing, and tooling**
+- Uses **Foundry's testing, fuzzing, and tooling**
 - Separates **business logic from mechanics**
 - Documents **design decisions explicitly**
 - Provides a **clean base for further token systems** (vesting, staking, governance, bridges, etc.)
 
 This is intended to be:
+
 - A **starting point for serious token projects**
 - A **learning reference for professional Solidity engineers**
 - A **baseline for audits and production deployments**
 
 ---
 
+## Built With
+
+- **[Foundry](https://book.getfoundry.sh/)** - Blazing fast, portable and modular toolkit for Ethereum application development
+- **[Solady](https://github.com/Vectorized/solady)** - Gas-optimized Solidity libraries by Vectorized
+  - Core ERC20 implementation inherits from Solady's highly optimized contracts
+
+---
+
 ## Architecture Overview
 
 The system is structured around:
@@ -51,6 +60,7 @@ The system is structured around:
   - Policy layers (who can mint, burn, pause, etc.)
 
 Design goals:
+
 - Predictable storage layout
 - Minimal branching in hot paths
 - Explicit revert reasons
@@ -89,19 +99,25 @@ Design goals:
 ## Engineering Principles
 
 ### 1. Correctness Over Convenience
+
 Every state mutation is explicit. No hidden side effects. No magical flows.
 
 ### 2. Invariants First
+
 The implementation is written around invariants:
+
 - Sum of balances == totalSupply
 - Transfers do not create or destroy value
 - Mint and burn are the only supply-changing operations
 
 ### 3. Minimal Surface Area
+
 No unnecessary features in the core layer. Policy features (roles, caps, pauses, etc.) are intended to be layered on top.
 
 ### 4. Audit-First Design
+
 The code is structured to be:
+
 - Readable
 - Traceable
 - Verifiable
@@ -119,6 +135,7 @@ This repository uses Foundry for:
 - Gas profiling
 
 Test categories include:
+
 - Transfer correctness
 - Allowance behavior
 - Mint/Burn supply invariants
@@ -133,102 +150,206 @@ Test categories include:
   - Randomized mint/burn operations
 
 This ensures:
+
 - No silent balance corruption
 - No supply drift
 - No allowance desync
 
 ---
 
 ## Project Structure
-src/<br />
-├── ERC20.sol # Core ERC20 implementation<br />
-├── interfaces/<br />
-│ └── IERC20.sol # ERC20 interface<br />
-└── extensions/ # Future extensions (cap, roles, etc<br />
-<br />
-test/<br />
-├── ERC20.t.sol # Unit tests<br />
-├── ERC20.fuzz.t.sol # Fuzz tests<br />
-└── ERC20.invariant.t.sol# Invariant tests<br />
-<br />
-##Extending This Implementation
+
+```
+src/
+├── ERC20.sol                    # Core ERC20 implementation
+├── interfaces/
+│   └── IERC20.sol              # ERC20 interface
+└── extensions/                  # Future extensions (cap, roles, etc.)
+
+test/
+├── ERC20.t.sol                 # Unit tests
+├── ERC20.fuzz.t.sol            # Fuzz tests
+└── ERC20.invariant.t.sol       # Invariant tests
+```
+
+---
+
+## Extending This Implementation
 
 This base is intentionally clean and minimal.
+
 It is designed to be extended with:
-Capped supply
-Role-based minting
-Pausable transfers
-Vesting systems
-Staking systems
-Governance voting power
-Bridging adapters
-Upgradeable proxies
+
+- Capped supply
+- Role-based minting
+- Pausable transfers
+- Vesting systems
+- Staking systems
+- Governance voting power
+- Bridging adapters
+- Upgradeable proxies
+
 Without modifying the core accounting engine.
-=======
-## Foundry
 
-**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
+---
 
-Foundry consists of:
+## Getting Started
 
-- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
-- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
-- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
-- **Chisel**: Fast, utilitarian, and verbose solidity REPL.
+### Prerequisites
 
-## Documentation
+- [Foundry](https://book.getfoundry.sh/getting-started/installation)
 
-https://book.getfoundry.sh/
+### Installation
 
-## Usage
+```shell
+# Clone the repository
+git clone https://github.com/CodesenSys/erc20-implementation.git
+cd erc20-implementation
+
+# Install dependencies
+forge install
+```
 
 ### Build
 
 ```shell
-$ forge build
+forge build
 ```
 
 ### Test
 
 ```shell
-$ forge test
+# Run all tests
+forge test
+
+# Run tests with gas reporting
+forge test --gas-report
+
+# Run specific test file
+forge test --match-path test/ERC20.t.sol
+
+# Run with verbosity
+forge test -vvv
 ```
 
 ### Format
 
 ```shell
-$ forge fmt
+forge fmt
 ```
 
 ### Gas Snapshots
 
 ```shell
-$ forge snapshot
+forge snapshot
 ```
 
-### Anvil
+### Deploy
 
 ```shell
-$ anvil
+forge script script/Deploy.s.sol:DeployScript --rpc-url <your_rpc_url> --private-key <your_private_key>
 ```
 
-### Deploy
+---
 
-```shell
-$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
-```
+## Foundry Toolkit
 
-### Cast
+**Foundry** consists of:
 
-```shell
-$ cast <subcommand>
-```
+- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools)
+- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data
+- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network
+- **Chisel**: Fast, utilitarian, and verbose solidity REPL
 
-### Help
+### Useful Commands
 
 ```shell
-$ forge --help
-$ anvil --help
-$ cast --help
+# Get help
+forge --help
+anvil --help
+cast --help
+
+# Start local node
+anvil
+
+# Interact with contracts
+cast <subcommand>
 ```
->>>>>>> dev
+
+For more details, see the [Foundry Book](https://book.getfoundry.sh/).
+
+---
+
+## Security Considerations
+
+This implementation follows security best practices:
+
+- ✅ Uses Solidity ^0.8 for built-in overflow protection
+- ✅ Inherits from battle-tested Solady libraries
+- ✅ Extensive test coverage including fuzz and invariant tests
+- ✅ Explicit error handling with custom errors
+- ✅ Zero address checks on critical operations
+- ✅ Follows checks-effects-interactions pattern
+
+**However**, before deploying to production:
+
+- Conduct a professional security audit
+- Review all extension/policy layers added on top
+- Test thoroughly on testnets
+- Consider formal verification for high-value deployments
+
+---
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+Please ensure:
+
+- All tests pass
+- Code is formatted with `forge fmt`
+- New features include tests
+- Documentation is updated
+
+---
+
+## License & Attribution
+
+This project is licensed under the MIT License
+
+### Third-Party Dependencies
+
+This implementation builds upon:
+
+- **[Solady](https://github.com/Vectorized/solady)** by Vectorized  
+  Licensed under the MIT License  
+  Copyright (c) 2022 Solady Contributors
+
+Special thanks to the Solady team for their highly optimized and gas-efficient Solidity libraries.
+
+---
+
+## Disclaimer
+
+This software is provided "as is", without warranty of any kind. Use at your own risk. Always conduct thorough testing and professional audits before deploying to production environments.
+
+---
+
+## Contact
+
+**CodesenSys**
+
+- GitHub: [@CodesenSys](https://github.com/CodesenSys)
+- Website: [codesensys.com](https://codesensys.com)
+
+For questions or support, please open an issue on GitHub.
+
+---
+
+Built with ❤️ by CodesenSys