refactor(stQRL): Switch from rebasing to fixed-balance model

README.md

@@ -4,13 +4,13 @@ Decentralized liquid staking protocol for QRL Zond. Deposit QRL, receive stQRL,
 
 ## Overview
 
-QuantaPool enables QRL holders to participate in Proof-of-Stake validation without running their own validator nodes. Users deposit QRL and receive stQRL, a rebasing token whose balance automatically adjusts as validators earn rewards or experience slashing.
+QuantaPool enables QRL holders to participate in Proof-of-Stake validation without running their own validator nodes. Users deposit QRL and receive stQRL, a fixed-balance token where `balanceOf()` returns stable shares and `getQRLValue()` returns the current QRL equivalent (which grows with rewards).
 
 ### Key Features
 
 - **Liquid Staking**: Receive stQRL tokens that can be transferred while underlying QRL earns rewards
-- **Rebasing Token**: Balance increases automatically as validators earn rewards (Lido-style)
-- **Slashing-Safe**: Rebasing design handles slashing events by proportionally reducing all holders' balances
+- **Fixed-Balance Token**: Share balance stays constant (tax-friendly), QRL value grows with rewards
+- **Slashing-Safe**: Fixed-balance design handles slashing by proportionally reducing all holders' QRL value
 - **Trustless Sync**: No oracle needed - rewards detected via EIP-4895 balance increases
 - **Post-Quantum Secure**: Built on QRL's Dilithium signature scheme
 
@@ -33,9 +33,9 @@ QuantaPool enables QRL holders to participate in Proof-of-Stake validation witho
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                      stQRL-v2.sol                           │
-│  - Rebasing ERC-20 token                                    │
-│  - Shares-based accounting (Lido-style)                     │
-│  - balanceOf = shares × totalPooledQRL / totalShares        │
+│  - Fixed-balance ERC-20 token                               │
+│  - Shares-based accounting (wstETH-style)                   │
+│  - balanceOf = shares, getQRLValue = QRL equivalent         │
 └─────────────────────────────────────────────────────────────┘
                             │
                             ▼
@@ -50,20 +50,21 @@ QuantaPool enables QRL holders to participate in Proof-of-Stake validation witho
 
 | Contract | Purpose |
 |----------|---------|
-| `stQRL-v2.sol` | Rebasing liquid staking token |
+| `stQRL-v2.sol` | Fixed-balance liquid staking token |
 | `DepositPool-v2.sol` | User entry point, deposits/withdrawals, reward sync |
 | `ValidatorManager.sol` | Validator lifecycle tracking |
 
-## How Rebasing Works
+## How Fixed-Balance Model Works
 
 1. User deposits 100 QRL when pool has 1000 QRL and 1000 shares
-2. User receives 100 shares, balance shows 100 QRL
+2. User receives 100 shares, `balanceOf()` = 100 shares
 3. Validators earn 50 QRL rewards (pool now has 1050 QRL)
-4. User's balance = 100 × 1050 / 1000 = **105 QRL**
-5. User's shares unchanged, but balance "rebased" upward
+4. User's `balanceOf()` still = **100 shares** (unchanged, tax-friendly)
+5. User's `getQRLValue()` = 100 × 1050 / 1000 = **105 QRL**
 
 If slashing occurs (pool drops to 950 QRL):
-- User's balance = 100 × 950 / 1000 = **95 QRL**
+- User's `balanceOf()` still = **100 shares**
+- User's `getQRLValue()` = 100 × 950 / 1000 = **95 QRL**
 - Loss distributed proportionally to all holders
 
 ## Development
@@ -92,10 +93,14 @@ forge test -vvv
 
 ## Test Coverage
 
-- **46 tests passing** (stQRL-v2 + DepositPool-v2)
-- Rebasing math, multi-user rewards, slashing scenarios
+- **173 tests passing** (55 stQRL-v2 + 63 DepositPool-v2 + 55 ValidatorManager)
+- Share/QRL conversion math, multi-user rewards, slashing scenarios
 - Withdrawal flow with delay enforcement
+- Validator lifecycle (registration, activation, exit, slashing)
 - Access control and pause functionality
+- All error paths and revert conditions
+- Event emission verification
+- Admin functions (ownership, pause, emergency)
 - Fuzz testing for edge cases
 
 ## Status
@@ -106,13 +111,18 @@ forge test -vvv
 
 - [ ] Deploy v2 contracts to Zond testnet
 - [ ] Integrate staking UI into [qrlwallet.com](https://qrlwallet.com)
-- [ ] Add wstQRL wrapper (non-rebasing, for DeFi compatibility)
 
 ## Security
 
 - Slither static analysis completed (0 critical/high findings)
 - See `slither-report.txt` for full audit results
 
+## Acknowledgments
+
+- [Lido](https://lido.fi/) and [Rocket Pool](https://rocketpool.net/) for pioneering liquid staking designs
+- [The QRL Core Team](https://www.theqrl.org/) for building post-quantum secure blockchain infrastructure
+- [Robyer](https://github.com/robyer) for community feedback on the fixed-balance token model (tax implications of rebasing)
+
 ## License
 
 GPL-3.0