feat(test): add invariant fuzz testing with comprehensive handler

- Implement full invariant suite proving vault solvency and accounting integrity
  • invariant_solvency: balance == totalAssets + totalPendingAssets
  • invariant_pending_le_balance: pending never exceeds cash

- Add VaultHandler with realistic bounded actions:
  • deposit (respects user balance, caps at 5000 USDC)
  • partial requestRedeem with slippage simulation
  • cancelRedeem (respects claimableAt restriction)
  • claimRedeem with time warp and try/catch for liquidity failures
  • depositYield and rescindRedemption for admin paths

- Handler uses direct tuple unpacking from public mapping (no struct reconstruction)
- Tracks active request IDs to avoid invalid calls
- 20 ghost users for better interaction coverage

- Run config: 1000 runs × 128 depth — all invariants pass

This completes mathematical proof of core accounting correctness under arbitrary sequences.

Also:
- Finalize rescindRedemption (keep funds in vault, no transfer out)
- Add InsufficientLiquidity custom error for dry vault UX
- Remove unused RequestFrozen error

The vault now has proven economics, realistic ops flow, and compliance handling.

Author: tr-Kalyan

.github/workflows/audit.yml

@@ -35,6 +35,9 @@ jobs:
       - name: Run Unit Tests
         run: forge test -vvv
 
+      - name: Run Invariant Tests
+        run: forge test --mt invariant -vvv
+
       - name: Gas Snapshot
         run: forge snapshot --check --tolerance 5 # Allow 5% gas increase per function
 

foundry.toml

@@ -6,4 +6,9 @@ libs = ["lib"]
 remappings = [
     "@openzepplin/contracts = lib/openzeppelin-contracts/contracts"
 ]
+
+[invariant]
+runs = 1000
+depth = 128
+fail_on_revert = true
 # See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options

src/AsyncSettlementRWAVault.sol

@@ -12,6 +12,9 @@ import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol
 contract AsyncSettlementRWAVault is ERC4626, Ownable, ReentrancyGuard {
     using SafeERC20 for IERC20;
 
+    /* ================ ERRORS ================ */
+    error InsufficientLiquidity(); // Vault is dry
+
     /* ================ CONSTANTS & IMMUTABLES ================ */
 
     uint256 public constant MIN_DELAY = 24 hours; //(T+1)
@@ -58,6 +61,8 @@ contract AsyncSettlementRWAVault is ERC4626, Ownable, ReentrancyGuard {
         uint256 indexed requestId, address indexed owner, uint256 assetsReturned, uint256 sharesMinted
     );
 
+    event RedemptionRescinded(uint256 indexed requestId, string reason);
+
     /* ================ CONSTRUCTOR ================ */
     constructor(IERC20 asset_, string memory name_, string memory symbol_)
         ERC4626(asset_)
@@ -89,6 +94,8 @@ contract AsyncSettlementRWAVault is ERC4626, Ownable, ReentrancyGuard {
         return super.totalAssets() - totalPendingAssets;
     }
 
+    /* ================ CORE FUNCTIONS ================ */
+    
     /**
      * @notice Distributes Net Yield to the vault.
      * @dev We assume Fees/Expenses were already deducted off-chain.
@@ -153,6 +160,19 @@ contract AsyncSettlementRWAVault is ERC4626, Ownable, ReentrancyGuard {
         emit RedemptionRequested(requestId, owner, receiver, shares, expectedAssets, block.timestamp + settlementDelay);
     }
 
+    function rescindRedemption(uint256 requestId, string calldata reason) external onlyOwner {
+        RedemptionRequest storage request = pendingRedemptions[requestId];
+
+        require(request.owner != address(0), "Invalid request");
+        uint256 assets = request.assetAtRequest;
+
+        totalPendingAssets -= assets;
+        delete pendingRedemptions[requestId];
+
+        emit RedemptionRescinded(requestId, reason);
+
+    }
+
     function claimRedeem(uint256 requestId) external nonReentrant {
         RedemptionRequest storage request = pendingRedemptions[requestId];
 
@@ -164,6 +184,12 @@ contract AsyncSettlementRWAVault is ERC4626, Ownable, ReentrancyGuard {
         address receiver = request.receiver;
         uint256 assetsToSend = request.assetAtRequest;
 
+        // Liquidity Check
+        uint256 vaultBalance = IERC20(asset()).balanceOf(address(this));
+        if (vaultBalance < assetsToSend) {
+            revert InsufficientLiquidity();
+        }
+
         // Delete request to prevent double-claim + refund gas
         totalPendingAssets -= request.assetAtRequest;
         delete pendingRedemptions[requestId];

src/Interfaces/IAsyncSettlementValut.sol

@@ -5,34 +5,71 @@ import {IERC4626} from "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.s
 
 // Extending ERC-4626 for standard functions + adding ERC-7540 stule async redeem
 interface IAsyncSettlementVault is IERC4626 {
-    /* ================ ERC-7540 ASYNC REDEEM EXTENSIONS ================ */
+    /* ================ ASYNC REDEEM EXTENSIONS ================ */
 
     /**
-     * @notice Request redemption of shares. Burns shares immediately, queues claim.
+     * @notice Request asynchronous redemption
+     * @dev Request redemption of shares. Burns shares immediately, queues claim.
      * @param shares Amount of valt shares to redeem
+     * @param receiver Recipient of assets on claim
      * @param owner Owner of the shares (allows meta-tx)
+     * @param minAssets Minimum acceptable assets (slippage protection)
      * @return requestId Unique ID for this pending redemption
-     */
-    function requestRedeem(uint256 shares, address owner) external returns (uint256 requestId);
+    */
+    function requestRedeem(
+        uint256 shares,
+        address receiver,
+        address owner,
+        uint256 minAssets
+    ) external returns (uint256 requestId);
+    
+    /**
+     * @notice Cancel a pending redemption request
+     * @dev Only callable before claimableAt, re-mints shares at current price
+     * @param requestId The pending request to cancel
+    */
+    function cancelRedeem(uint256 requestId) external;
+
 
     /**
-     * @notice View how many assets a pending request will yield when claimable
-     * @param requestId The pending request ID
-     * @return assets Expected underlying assets (including accrued yeild at claim time)
-     * @return claimableAt
-     */
+     * @notice View pending redemption details
+     * @param requestId The request ID
+     * @return assets Snapshotted assets owed
+     * @return claimableAt Timestamp when claimable
+    */
     function pendingRedeemRequest(uint256 requestId) external view returns (uint256 assets, uint256 claimableAt);
 
     /**
-     * @notice Claim a matured pending redemption
-     * @dev Re-uses ERC-4626 redeem/withdraw semantics for claiming
+     * @notice Claim matured redemption
      * @param requestId The request to claim
-     */
+    */
     function claimRedeem(uint256 requestId) external;
 
-    /* ================ CONFIG & EVENTS ================ */
+    /* ================ EVENTS ================ */
+
+    event RedemptionRequested(
+        uint256 indexed requestId,
+        address indexed owner,
+        address indexed receiver,
+        uint256 shares,
+        uint256 expectedAssets,
+        uint256 claimableAt
+    );
+
+    event RedemptionCancelled(
+        uint256 indexed requestId,
+        address indexed owner,
+        uint256 assetsReturned,
+        uint256 sharesMinted
+    );
+
+    event RedemptionClaimed(
+        uint256 indexed requestId,
+        address indexed receiver,
+        uint256 assets
+    );
+
+    event YieldDistributed(uint256 amount, uint256 newSharePrice);
 
-    event RedemptionRequested(uint256 indexed requestId, address indexed owner, uint256 shares, uint256 expectedAssets);
-    event RedemptionClaimed(uint256 indexed requestId, address indexed receiver, uint256 assets);
     event SettlementDelayUpdated(uint256 newDelay);
 }

test/fuzz/VaultHandler.t.sol

@@ -0,0 +1,171 @@
+// test/invariants/VaultHandler.sol
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {Test} from "forge-std/Test.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {AsyncSettlementRWAVault} from "../../src/AsyncSettlementRWAVault.sol";
+
+contract VaultHandler is Test {
+    AsyncSettlementRWAVault public vault;
+    IERC20 public usdc;
+    address public admin;
+
+    address[] public users;
+    uint256[] public activeRequestIds; 
+
+    uint256 public constant INITIAL_USER_BALANCE = 10_000 * 1e6;
+    uint256 public constant MAX_YIELD = 500 * 1e6;
+
+    constructor(AsyncSettlementRWAVault _vault, IERC20 _usdc) {
+        vault = _vault;
+        usdc = _usdc;
+        admin = vault.owner();
+
+        // Create 20 ghost users for better coverage
+        for (uint256 i = 0; i < 20; i++) {
+            address user = makeAddr(vm.toString(i));
+            users.push(user);
+            deal(address(usdc), user, INITIAL_USER_BALANCE);
+        }
+    }
+
+    /* ================ USER ACTIONS ================ */
+
+    function deposit(uint256 userId, uint256 amount) public {
+        userId = bound(userId, 0, users.length - 1);
+        address user = users[userId];
+
+        // FIX: Check actual balance to prevent 'ERC20InsufficientBalance' reverts
+        uint256 balance = usdc.balanceOf(user);
+        if (balance < 1e6) return; // Skip if user is broke
+
+        // Cap deposit to actual balance or 5000 (whichever is lower)
+        uint256 maxDeposit = balance > 5000 * 1e6 ? 5000 * 1e6 : balance;
+        amount = bound(amount, 1e6, maxDeposit);
+
+        vm.startPrank(user);
+        usdc.approve(address(vault), amount);
+        vault.deposit(amount, user);
+        vm.stopPrank();
+    }
+
+    function requestRedeem(uint256 userId, uint256 sharePercent, uint256 minAssetsOffset) public {
+        userId = bound(userId, 0, users.length - 1);
+        sharePercent = bound(sharePercent, 1, 100); 
+
+        address user = users[userId];
+        uint256 shares = vault.balanceOf(user);
+
+        if (shares == 0) return;
+
+        uint256 sharesToRedeem = (shares * sharePercent) / 100;
+        if (sharesToRedeem == 0) return;
+
+        uint256 expectedAssets = vault.previewRedeem(sharesToRedeem);
+        
+        // Slippage calc
+        uint256 offset = bound(minAssetsOffset, 0, expectedAssets / 10);
+        uint256 minAssets = expectedAssets - offset;
+
+        vm.startPrank(user);
+        uint256 requestId = vault.requestRedeem(sharesToRedeem, user, user, minAssets);
+        activeRequestIds.push(requestId);
+        vm.stopPrank();
+    }
+
+    function cancelRedeem(uint256 requestIndex) public {
+        if (activeRequestIds.length == 0) return;
+
+        requestIndex = bound(requestIndex, 0, activeRequestIds.length - 1);
+        uint256 requestId = activeRequestIds[requestIndex];
+
+        // FIX: Tuple unpacking (No struct)
+        (address owner, , , , uint256 claimableAt) = vault.pendingRedemptions(requestId);
+
+        if (owner == address(0)) {
+            _removeRequestId(requestIndex);
+            return;
+        }
+
+        // FIX: Respect your contract condition (Only cancel BEFORE claimableAt)
+        if (block.timestamp >= claimableAt) {
+            // It's too late to cancel, so we skip calling the function
+            // (Calling it would revert, wasting a fuzz run)
+            return; 
+        }
+
+        vm.prank(owner);
+        vault.cancelRedeem(requestId);
+
+        _removeRequestId(requestIndex);
+    }
+
+    function claimRedeem(uint256 requestIndex) public {
+        if (activeRequestIds.length == 0) return;
+
+        requestIndex = bound(requestIndex, 0, activeRequestIds.length - 1);
+        uint256 requestId = activeRequestIds[requestIndex];
+
+        (address owner, , , , uint256 claimableAt) = vault.pendingRedemptions(requestId);
+
+        if (owner == address(0)) {
+            _removeRequestId(requestIndex);
+            return;
+        }
+
+        // Warp time if needed
+        if (block.timestamp < claimableAt) {
+            vm.warp(claimableAt + 1);
+        }
+
+        vm.prank(owner);
+        try vault.claimRedeem(requestId) {
+            _removeRequestId(requestIndex);
+        } catch {
+            // Failed (likely insufficient liquidity) - keep in list
+        }
+    }
+
+    /* ================ ADMIN ACTIONS ================ */
+
+    function depositYield(uint256 amount) public {
+        amount = bound(amount, 1e6, MAX_YIELD);
+
+        vm.startPrank(admin);
+        deal(address(usdc), admin, amount);
+        usdc.approve(address(vault), amount);
+        vault.depositYield(amount);
+        vm.stopPrank();
+    }
+
+    function rescindRedemption(uint256 requestIndex, string calldata reason) public {
+        if (activeRequestIds.length == 0) return;
+
+        requestIndex = bound(requestIndex, 0, activeRequestIds.length - 1);
+        uint256 requestId = activeRequestIds[requestIndex];
+
+        (address owner, , , ,) = vault.pendingRedemptions(requestId);
+        if (owner == address(0)) {
+            _removeRequestId(requestIndex);
+            return;
+        }
+
+        vm.prank(admin);
+        vault.rescindRedemption(requestId, reason);
+
+        _removeRequestId(requestIndex);
+    }
+
+    /* ================ INTERNAL ================ */
+
+    function _removeRequestId(uint256 index) internal {
+        activeRequestIds[index] = activeRequestIds[activeRequestIds.length - 1];
+        activeRequestIds.pop();
+    }
+
+    // Helper for invariants to get active requests
+    function numActiveRequests() public view returns (uint256) {
+        return activeRequestIds.length;
+    }
+}

test/fuzz/VaultInvariants.t.sol

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {Test} from "forge-std/Test.sol";
+import {AsyncSettlementRWAVault} from "../../src/AsyncSettlementRWAVault.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {VaultHandler} from "./VaultHandler.t.sol";
+import {MockUSDC} from "../mocks/MockUSDC.sol";
+
+
+contract VaultInvariants is Test {
+    AsyncSettlementRWAVault vault;
+    IERC20 usdc;
+    VaultHandler handler;
+
+    function setUp() public {
+        usdc = IERC20(address(new MockUSDC()));
+        vault = new AsyncSettlementRWAVault(usdc, "Async RWA Vault", "arUSDC");
+        handler = new VaultHandler(vault, usdc);
+        
+        targetContract(address(handler));
+    }
+
+    /* ================ CORE INVARIANTS ================ */
+
+    /// @notice The Vault's math must always balance.
+    /// Total Cash = (Invested/Free Assets) + (Locked Pending Payables)
+    function invariant_solvency() public view {
+        uint256 totalCash = usdc.balanceOf(address(vault));
+        uint256 accounting = vault.totalAssets() + vault.totalPendingAssets();
+
+        assertEq(totalCash, accounting, "Solvency broken: Cash != Assets + Liabilities");
+    }
+
+    /// @notice We should never promise to pay more than we physically hold
+    /// (Note: This assumes funds are not invested off-chain during this test)
+    function invariant_solvency_liquidity() public view {
+        assertLe(
+            vault.totalPendingAssets(),
+            usdc.balanceOf(address(vault)),
+            "Insolvent: Liabilities exceed Cash"
+        );
+    }
+
+
+}