Update readme (#71)

* Initial README.md by Claude

* Remove alpha & multi platform

* Remove badges

* Manual changes

* Remove API

* Remove String Utilities

* Remove

* Reorder

* Split assertions

* Tweaks

* Rewrite

* Add disclaimer

* Minor tweaks

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Rename licence file

* Change license to GPL v3

* Undo license file rename

* Update license to GPL v3 everywhere

* License attributions

* Restructure

* Contributing

* Contributing

* Simplified introduction text

* Tweaks

* Reorder

* Update README.md

---------

Co-authored-by: ljz3 <[email protected]>

Author: rappie

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to Fuzzlib
+
+Thanks for your interest in contributing to Fuzzlib!
+
+## Development Setup
+
+### Prerequisites
+
+- [Foundry](https://getfoundry.sh/)
+
+### Setup
+
+```bash
+git clone https://github.com/your-username/fuzzlib.git
+cd fuzzlib
+forge install
+```
+
+### Testing
+
+```bash
+# Run all tests
+forge test
+
+# Run tests with increased fuzz runs
+forge test --fuzz-runs 10000
+
+# Run Echidna E2E tests
+python3 test/e2e/echidna/run-echidna.py
+```
+
+## Contributing Workflow
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature-name`
+3. Make your changes
+4. Add tests
+5. Ensure all tests pass: `forge test`
+6. Format code: `forge fmt`
+7. Commit and push
+8. Open a Pull Request against the main repository
+
+## Development Guidelines
+
+- Keep code simple and maintainable
+- Follow existing code patterns and conventions
+- Add comprehensive tests for new functionality
+- Update documentation as needed
+
+## Issues
+
+- Check existing issues before creating new ones
+- Provide clear reproduction steps
+- Include sample code if relevant

LICENSE

@@ -1,14 +1,205 @@
 # Fuzzlib
-Fuzzlib is an unopinionated Solidity library designed for both stateful and stateless fuzzing of smart contracts. It provides a collection of useful functions and libraries designed to streamline fuzzing harness development with Echidna, Medusa, and Foundry, making the process easier and more efficient.
 
-**Fuzzlib is still in alpha and under active development with potential future breaking changes!**
+General purpose unopinionated Solidity fuzzing library for stateful and stateless fuzzing. Compatible with Echidna, Medusa, and Foundry.
 
-## Branches
-* `main`: Latest `fl.` namespace
-* `v0_2`: Old namespace version for backwards compatibility
+Provides common utilities for fuzz testing through a simple `fl` namespace: assertions, value clamping, logging, math operations, and more.
 
+## Key Features
 
-## Known limitations
-- Signed integer clamping is limited to int128 range to avoid overflow issues in range calculations
+- **Basic Assertions**: Helpers for common test conditions and equality checks 
+- **Advanced Assertions**: Utilities like error handling via `errAllow` for expected failures
+- **Value Clamping**: Clamp values to ranges with uniform distribution for better fuzzing
+- **Logging Utilities**: Unified logging for debugging and tracing
+- **Math Utilities**: Operations like min, max, absolute value, and difference calculations
+- **Random Utilities**: Fisher-Yates array shuffling
+- **Function Call Helpers**: Utilities for making function calls with actor pranking
+- **Comprehensive Testing**: Extensive test suite with both unit and fuzz tests
+- **Well-Documented**: Clear and complete, following OpenZeppelin-style conventions
 
+## Installation
 
+### Using Foundry
+
+```bash
+forge install perimetersec/fuzzlib
+```
+
+### Using npm
+
+```bash
+npm install @perimetersec/fuzzlib
+```
+
+Add to your `remappings.txt`:
+```
+fuzzlib/=lib/fuzzlib/src/
+```
+
+## Quick Start
+
+Create a simple fuzzing test by extending `FuzzBase`:
+
+```solidity
+import {FuzzBase} from "fuzzlib/FuzzBase.sol";
+
+contract MyFuzzer is FuzzBase {
+    function testMath(uint256 a, uint256 b) public {
+        // Clamp inputs to reasonable ranges
+        uint256 x = fl.clamp(a, 0, 1000);
+        uint256 y = fl.clamp(b, 0, 1000);
+         
+        // Log for debugging
+        fl.log("Testing max function. x =", x);
+        fl.log("Testing max function. y =", y);
+       
+        // Test mathematical properties
+        fl.gte(fl.max(x, y), x, "Max should be >= x");
+        fl.gte(fl.max(x, y), y, "Max should be >= y");
+    }
+}
+```
+
+
+## Function Reference
+
+### Basic Assertions
+
+```solidity
+// Fundamental assertions
+fl.t(exists, "Property X exists");
+fl.eq(result, 100, "Result should equal 100");
+fl.neq(userA, userB, "Users should be different");
+
+// Comparison assertions
+fl.gt(balance, 1000, "Balance should be greater than 1000");
+fl.gte(amount, 50, "Amount should be greater than or equal to 50");
+fl.lt(fee, 100, "Fee should be less than 100");
+fl.lte(price, 500, "Price should be less than or equal to 500");
+```
+
+### Advanced Assertions
+
+```solidity
+// Allow specific require messages
+string[] memory allowedMessages = new string[](1);
+allowedMessages[0] = "Insufficient balance";
+fl.errAllow(errorData, allowedMessages, "Message X should be allowed");
+
+// Allow specific custom errors
+bytes4[] memory allowedErrors = new bytes4[](1);
+allowedErrors[0] = CustomError.selector;
+fl.errAllow(errorSelector, allowedErrors, "Error X should be allowed");
+
+// Combined error handling
+fl.errAllow(errorData, allowedMessages, allowedErrors, "Either should be allowed");
+```
+
+### Value Clamping
+
+```solidity
+// Value clamping with uniform distribution
+uint256 clamped = fl.clamp(inputValue, 0, 100);
+
+// Clamp to greater than value
+uint256 clampedGt = fl.clampGt(inputValue, 50);
+
+// Clamp to greater than or equal
+uint256 clampedGte = fl.clampGte(inputValue, 50);
+
+// Clamp to less than value
+uint256 clampedLt = fl.clampLt(inputValue, 100);
+
+// Clamp to less than or equal
+uint256 clampedLte = fl.clampLte(inputValue, 100);
+```
+
+### Logging
+
+```solidity
+// Simple logging
+fl.log("Testing scenario");
+
+// Logging with values
+fl.log("Balance:", balance);
+fl.log("User count:", 42);
+
+// Failure logging
+fl.logFail("This test failed");
+fl.logFail("Invalid amount:", amount);
+```
+
+### Math Utilities
+
+```solidity
+// Min/max operations
+uint256 maximum = fl.max(150, 300);
+int256 minimum = fl.min(-50, 25);
+
+// Absolute value and difference
+uint256 absolute = fl.abs(-42);
+uint256 difference = fl.diff(100, 75);
+```
+
+### Random Utilities
+
+```solidity
+// Shuffle arrays
+uint256[] memory array = new uint256[](10);
+fl.shuffleArray(array, entropy);
+```
+
+### Function Call Helpers
+
+```solidity
+// Make function calls
+bytes memory result = fl.doFunctionCall(
+    address(target),
+    abi.encodeWithSignature("getValue()"),
+    msg.sender  // actor
+);
+
+// Calls with automatic pranking
+(bool success, bytes memory data) = fl.doFunctionCall(
+    address(target),
+    abi.encodeWithSignature("transfer(address,uint256)", recipient, amount),
+    sender
+);
+
+// Static calls (view functions)
+(bool success, bytes memory data) = fl.doFunctionStaticCall(
+    address(target),
+    abi.encodeWithSignature("balanceOf(address)", user)
+);
+```
+
+## Known Limitations
+
+- **Signed Integer Clamping**: Limited to `int128` range to avoid overflow issues in range calculations
+- **Gas Optimization**: Library prioritizes functionality over gas optimization
+- **Function Selector Clashing**: If the error selector clashes with `Error(string)` when using errAllow, unexpected behavior may happen
+
+
+## Roadmap
+
+- [ ] Support for more platforms
+- [ ] Add more helper functions
+- [ ] Performance optimizations
+
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
+
+
+## License
+
+This project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.
+
+Some portions of this code are modified from [Crytic Properties](https://github.com/crytic/properties/blob/main/contracts/util/PropertiesHelper.sol), which is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
+
+Some portions of this code are modified from [OpenZeppelin Contracts](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/math/SafeCast.sol), which is licensed under the MIT License.
+
+
+## Disclaimer
+
+This software is provided as-is without warranty. The main branch contains new and experimental features that may be unstable. For production use, we recommend using official tagged releases which have been thoroughly tested. While we are not responsible for any bugs or issues, we maintain a bug bounty program that applies to official releases only.

README.md

@@ -4,7 +4,7 @@
   "description": "Solidity Fuzzing Library",
   "homepage": "https://github.com/perimetersec/fuzzlib#readme",
   "author": "Perimeter <[email protected]>",
-  "license": "MIT",
+  "license": "GPL-3.0",
   "files": [
     "src/**/*"
   ],

package.json

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: GPL-3.0-or-later
 pragma solidity ^0.8.0;
 
 /**

src/Constants.sol

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: GPL-3.0-or-later
 pragma solidity ^0.8.0;
 
 import {Fuzzlib} from "./Fuzzlib.sol";

src/FuzzBase.sol

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: GPL-3.0-or-later
 pragma solidity ^0.8.0;
 
 /**

src/FuzzLibString.sol

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: GPL-3.0-or-later
 pragma solidity ^0.8.0;
 
 /**

src/FuzzSafeCast.sol

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: GPL-3.0-or-later
 pragma solidity ^0.8.0;
 
 import {HelperBase} from "./helpers/HelperBase.sol";

src/Fuzzlib.sol

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: GPL-3.0-or-later
 pragma solidity ^0.8.0;
 
 import {Constants} from "./Constants.sol";