Rewrite README with professional formatting

Author: SP1R4

README.md

@@ -1,59 +1,193 @@
+<div align="center">
+
 # FundForwarder
 
-A Solidity smart contract that receives ETH deposits and automatically forwards them to a predefined target wallet. Built with Hardhat and OpenZeppelin v5.
+**A non-custodial ETH forwarding smart contract built on Ethereum**
+
+[![Solidity](https://img.shields.io/badge/Solidity-0.8.20-363636?logo=solidity)](https://soliditylang.org/)
+[![Hardhat](https://img.shields.io/badge/Built%20with-Hardhat-yellow)](https://hardhat.org/)
+[![OpenZeppelin](https://img.shields.io/badge/OpenZeppelin-v5.0.2-4E5EE4?logo=openzeppelin)](https://www.openzeppelin.com/contracts)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Tests](https://img.shields.io/badge/Tests-32%20passing-brightgreen)]()
+[![Coverage](https://img.shields.io/badge/Coverage-100%25%20lines-brightgreen)]()
+
+</div>
+
+---
+
+## Overview
+
+FundForwarder is a production-ready Solidity smart contract that accepts ETH deposits and instantly forwards them to a designated target wallet. It is designed for scenarios where a fixed, public-facing deposit address is needed while retaining the flexibility to update the destination — all secured by timelocks, two-step ownership, and pause controls.
+
+### How It Works
+
+```
+Sender ──► [ FundForwarder Contract ] ──► Target Wallet
+              │
+              ├─ Validates minimum deposit
+              ├─ Emits Deposit event
+              ├─ Forwards full balance
+              └─ Emits Forwarded event
+```
+
+---
 
 ## Features
 
-- Automatic ETH forwarding on deposit
-- Configurable minimum deposit amount (capped at 10 ETH)
-- Time-locked target wallet changes (24-hour delay)
-- Pausable deposits for emergency scenarios
-- Owner fund recovery
-- Two-step ownership transfer (Ownable2Step)
-- Reentrancy protection
+| Feature | Description |
+|---|---|
+| **Instant Forwarding** | ETH is forwarded to the target wallet in the same transaction as the deposit |
+| **Minimum Deposit** | Configurable threshold to filter dust/spam transactions (capped at 10 ETH) |
+| **Time-locked Wallet Changes** | 24-hour mandatory delay before a new target wallet takes effect |
+| **Two-step Ownership (Ownable2Step)** | Ownership transfers require explicit acceptance, preventing irreversible mistakes |
+| **Pausable** | Owner can halt all deposits during emergencies or maintenance |
+| **Emergency Recovery** | Owner can withdraw any ETH stuck in the contract |
+| **Reentrancy Protection** | Guards against reentrancy on deposit and recovery paths |
+
+---
+
+## Architecture
+
+```
+contracts/
+├── FundForwarder.sol          # Main contract
+└── test/
+    ├── ForceFeeder.sol        # Test helper — force-sends ETH
+    └── Reverter.sol           # Test helper — always-reverting receiver
+```
+
+### Contract Inheritance
+
+```
+Ownable ─► Ownable2Step ─┐
+            Pausable ─────┤── FundForwarder
+      ReentrancyGuard ────┘
+```
+
+### Access Control
+
+| Function | Access | Description |
+|---|---|---|
+| `receive()` | Public | Accept and forward ETH deposits |
+| `fallback()` | Public | Rejects calls with calldata |
+| `requestTargetWalletChange()` | Owner | Initiate a wallet change (starts 24h timelock) |
+| `finalizeTargetWalletChange()` | Owner | Apply the pending wallet change after timelock |
+| `cancelTargetWalletChange()` | Owner | Cancel a pending wallet change |
+| `updateMinDeposit()` | Owner | Update the minimum deposit threshold |
+| `pause()` / `unpause()` | Owner | Toggle deposit acceptance |
+| `recoverFunds()` | Owner | Withdraw stuck ETH to the owner |
+| `transferOwnership()` | Owner | Initiate two-step ownership transfer |
+| `acceptOwnership()` | Pending Owner | Accept ownership transfer |
+
+---
+
+## Getting Started
+
+### Prerequisites
 
-## Setup
+- [Node.js](https://nodejs.org/) >= 18
+- [npm](https://www.npmjs.com/) >= 9
+
+### Installation
 
 ```bash
+git clone https://github.com/SP1R4/FundsForwarder.git
+cd FundsForwarder
 npm install
+```
+
+### Environment Setup
+
+```bash
 cp .env.example .env
-# Fill in .env with your keys
 ```
 
-## Compile
+Fill in your `.env`:
+
+```env
+SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY
+PRIVATE_KEY=your_deployer_private_key
+ETHERSCAN_API_KEY=your_etherscan_key
+TARGET_WALLET=0xYourTargetWalletAddress
+REPORT_GAS=false
+```
+
+> **Warning:** Never commit your `.env` file. It is excluded via `.gitignore`.
+
+---
+
+## Usage
+
+### Compile
 
 ```bash
 npx hardhat compile
 ```
 
-## Test
+### Test
 
 ```bash
 npx hardhat test
 ```
 
-## Coverage
+### Coverage
 
 ```bash
 npx hardhat coverage
 ```
 
-## Gas Report
+### Gas Report
 
 ```bash
 REPORT_GAS=true npx hardhat test
 ```
 
-## Deploy
+### Deploy to Sepolia
 
 ```bash
 npx hardhat run scripts/deploy.js --network sepolia
 ```
 
-## Security Model
+The deploy script reads `TARGET_WALLET` from `.env` and automatically verifies the contract on Etherscan after deployment.
+
+---
+
+## Test Suite
+
+32 tests across 8 categories with **100% line and function coverage**.
+
+```
+  FundForwarder
+    Deployment (6 tests)
+    Deposits & Forwarding (4 tests)
+    Wallet Change Flow (8 tests)
+    MinDeposit Updates (4 tests)
+    Pause / Unpause (3 tests)
+    Recovery (3 tests)
+    Ownable2Step (2 tests)
+    Fallback (1 test)
+    Edge Cases (1 test)
+
+  32 passing
+```
+
+---
+
+## Security Considerations
+
+- **Timelock on wallet changes** — A mandatory 24-hour delay between requesting and finalizing a target wallet change prevents instant fund redirection in the event of a compromised owner key, giving stakeholders time to respond.
+- **Ownable2Step** — Prevents ownership from being accidentally transferred to an incorrect or inaccessible address. The new owner must explicitly call `acceptOwnership()`.
+- **MAX_MIN_DEPOSIT cap** — The minimum deposit is bounded at 10 ETH to prevent misconfiguration that could lock the contract from receiving funds.
+- **No calldata accepted** — The `fallback()` function reverts on any call with data, reducing the attack surface to only plain ETH transfers.
+- **Reentrancy guards** — Applied to both `receive()` and `recoverFunds()` to prevent reentrancy exploits.
+
+### Known Limitations
+
+- The contract does not support ERC-20 token forwarding — ETH only.
+- `selfdestruct`-based force-sends can deposit ETH below `minDeposit` without triggering forwarding. The `recoverFunds()` function handles this case.
+
+---
+
+## License
 
-- **Ownable2Step**: Ownership transfers require explicit acceptance by the new owner, preventing accidental transfers to wrong addresses.
-- **Timelock**: Target wallet changes require a 24-hour waiting period, giving stakeholders time to react to unauthorized changes.
-- **Pausable**: The owner can pause deposits in case of emergency.
-- **ReentrancyGuard**: Prevents reentrancy attacks on deposit and recovery functions.
-- **MAX_MIN_DEPOSIT**: Caps the minimum deposit at 10 ETH to prevent owner misconfiguration.
+This project is licensed under the [ISC License](https://opensource.org/licenses/ISC).