feat: add rVirtual conversion via RVirtualConverter

.gitignore

@@ -22,4 +22,5 @@ fireblocks_secret.key
 .cursor/
 env*
 
-lib/
+lib/
+docs/

contracts/token/IRVirtualConverter.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+interface IRVirtualConverter {
+    function convertVirtualToRVirtual(
+        uint256 amount,
+        address rVirtualReceiver
+    ) external;
+
+    /// @notice The VIRTUAL token this converter accepts as input. Exposed so callers
+    ///         (e.g. veVirtual.setRVirtualConverter) can assert their own base token
+    ///         matches this converter's before wiring it in (see audit L-09).
+    function virtualToken() external view returns (address);
+}

contracts/token/RVirtualConverter.sol

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
+import "@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol";
+import "@openzeppelin/contracts-upgradeable/utils/ReentrancyGuardUpgradeable.sol";
+import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+/// @notice Open, permissionless 1:1 converter from VIRTUAL to rVirtual.
+///
+/// Pre-funded with the full rVirtual supply before launch - conversions draw down that
+/// balance rather than minting on demand. Any caller (a regular wallet, or veVirtual's
+/// convertVeVirtualToRVirtual()) uses the exact same convertVirtualToRVirtual() entrypoint;
+/// there is no privileged "veVirtual-only" path here.
+contract RVirtualConverter is
+    Initializable,
+    ReentrancyGuardUpgradeable,
+    AccessControlUpgradeable,
+    UUPSUpgradeable
+{
+    using SafeERC20 for IERC20;
+
+    bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");
+
+    address public virtualToken;
+    address public rVirtualToken;
+    /// @notice Treasury multisig that every conversion's incoming VIRTUAL is sent to
+    ///         directly. Set once at initialize() and never changed at runtime - VIRTUAL
+    ///         is never custodied by this contract, so there is no accumulated balance
+    ///         for a compromised or malicious admin key to sweep (see audit L-02). This
+    ///         is also why there is no adminWallet/withdrawVirtual() sweep mechanism here
+    ///         anymore (see audit I-06) - there is nothing left for it to sweep.
+    address public treasury;
+
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor() {
+        _disableInitializers();
+    }
+
+    event ConvertedVirtualToRVirtual(
+        address indexed caller,
+        address indexed rVirtualReceiver,
+        uint256 amount
+    );
+
+    function initialize(
+        address virtualToken_,
+        address rVirtualToken_,
+        address treasury_
+    ) external initializer {
+        __ReentrancyGuard_init();
+        __AccessControl_init();
+        __UUPSUpgradeable_init();
+
+        require(virtualToken_ != address(0), "Invalid virtual token");
+        require(rVirtualToken_ != address(0), "Invalid rVirtual token");
+        require(treasury_ != address(0), "Invalid treasury");
+        require(virtualToken_ != rVirtualToken_, "Tokens must differ");
+        // NOTE (audit M-02): the 1:1 conversion below is a raw-integer transfer with no
+        // decimals rescaling. This is safe only because VIRTUAL and rVirtual are both
+        // guaranteed by protocol design to use 18 decimals - if either token is ever
+        // redeployed/migrated to a different decimals value, this invariant must be
+        // re-verified (or an explicit decimals() equivalence check added) before wiring
+        // it in here.
+        virtualToken = virtualToken_;
+        rVirtualToken = rVirtualToken_;
+        treasury = treasury_;
+
+        _grantRole(DEFAULT_ADMIN_ROLE, _msgSender());
+        _grantRole(ADMIN_ROLE, _msgSender());
+    }
+
+    /// @notice Convert `amount` VIRTUAL (pulled from the caller) into `amount` rVirtual,
+    ///         sent to `rVirtualReceiver`. Fully open - no allowlist, no cap.
+    function convertVirtualToRVirtual(
+        uint256 amount,
+        address rVirtualReceiver
+    ) external nonReentrant {
+        require(amount > 0, "Amount must be greater than 0");
+        require(rVirtualReceiver != address(0), "Invalid receiver");
+
+        IERC20(virtualToken).safeTransferFrom(
+            _msgSender(),
+            treasury,
+            amount
+        );
+
+        uint256 balanceBefore = IERC20(rVirtualToken).balanceOf(rVirtualReceiver);
+        IERC20(rVirtualToken).safeTransfer(rVirtualReceiver, amount);
+        uint256 delivered = IERC20(rVirtualToken).balanceOf(rVirtualReceiver) - balanceBefore;
+        require(delivered == amount, "rVirtual delivery mismatch");
+
+        emit ConvertedVirtualToRVirtual(_msgSender(), rVirtualReceiver, delivered);
+    }
+
+    function _authorizeUpgrade(
+        address newImplementation
+    ) internal override onlyRole(ADMIN_ROLE) {}
+}

contracts/token/mocks/FeeOnTransferMock.sol

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+
+/// @notice TEST-ONLY mock modeling a fee-on-transfer / tax token, used to simulate the
+///         real rVirtual (GodToken)'s configurable transfer tax for security PoC purposes
+///         (see verify_H-2.js). NOT used in production - lives under contracts/token/mocks
+///         solely to be reachable by Hardhat's compiler for the test.
+///
+///         Deducts `feeBps` (out of 10_000) from every transfer/transferFrom, sending the
+///         fee portion to a burn/dead sink so the recipient always receives strictly less
+///         than the nominal transferred amount whenever feeBps > 0.
+contract FeeOnTransferMock is ERC20 {
+    uint256 public immutable feeBps; // e.g. 1000 = 10%
+    address public immutable feeSink;
+
+    constructor(
+        string memory name_,
+        string memory symbol_,
+        address initialAccount,
+        uint256 initialBalance,
+        uint256 feeBps_,
+        address feeSink_
+    ) ERC20(name_, symbol_) {
+        require(feeBps_ <= 10_000, "fee too high");
+        feeBps = feeBps_;
+        feeSink = feeSink_;
+        _mint(initialAccount, initialBalance);
+    }
+
+    function _update(address from, address to, uint256 value) internal override {
+        // Mint (from == address(0)) and burn (to == address(0)) pass through untaxed -
+        // only regular transfers between two live accounts are taxed, matching typical
+        // fee-on-transfer token behavior.
+        if (from == address(0) || to == address(0) || feeBps == 0) {
+            super._update(from, to, value);
+            return;
+        }
+
+        uint256 fee = (value * feeBps) / 10_000;
+        uint256 net = value - fee;
+
+        super._update(from, to, net);
+        if (fee > 0) {
+            super._update(from, feeSink, fee);
+        }
+    }
+}

contracts/token/mocks/MaliciousConverterMock.sol

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import "../IRVirtualConverter.sol";
+
+/// @notice TEST-ONLY mock simulating a malicious/repointed `rVirtualConverter` (see H-4 PoC,
+///         verify_H-4.js). Implements the exact `IRVirtualConverter` interface that
+///         `veVirtual.convertVeVirtualToRVirtual()` calls, but instead of delivering rVirtual
+///         1:1, it pulls the approved VIRTUAL via `transferFrom` and routes it to an
+///         attacker-controlled address, delivering ZERO rVirtual back to the victim. It does
+///         NOT revert - the call succeeds silently from veVirtual's perspective, so the
+///         lock deletion (which already happened before this external call) is never rolled
+///         back.
+contract MaliciousConverterMock is IRVirtualConverter {
+    address public immutable virtualToken;
+    address public immutable attacker;
+
+    constructor(address virtualToken_, address attacker_) {
+        virtualToken = virtualToken_;
+        attacker = attacker_;
+    }
+
+    function convertVirtualToRVirtual(
+        uint256 amount,
+        address /* rVirtualReceiver */
+    ) external override {
+        // Steal the approved VIRTUAL; deliver no rVirtual, and do not revert.
+        IERC20(virtualToken).transferFrom(msg.sender, attacker, amount);
+    }
+}

contracts/token/mocks/MockERC20SixDecimals.sol

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+
+/// @notice Minimal mock ERC20 with 6 decimals (like USDC), used ONLY to verify H-3
+/// (RVirtualConverter never asserts rVirtualToken.decimals() == 18).
+contract MockERC20SixDecimals is ERC20 {
+    constructor(
+        string memory name,
+        string memory symbol,
+        address initialAccount,
+        uint256 initialBalance
+    ) ERC20(name, symbol) {
+        _mint(initialAccount, initialBalance);
+    }
+
+    function decimals() public pure override returns (uint8) {
+        return 6;
+    }
+
+    function mint(address to, uint256 amount) public {
+        _mint(to, amount);
+    }
+}

contracts/token/mocks/NoOpConverterMock.sol

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "../IRVirtualConverter.sol";
+
+/// @notice TEST-ONLY mock for verify_H-10.js. Implements IRVirtualConverter but does NOT call
+///         transferFrom at all - simulates the specific scenario Chain Agent 2 analyzed where
+///         the converter call succeeds (no-op) without pulling the approved VIRTUAL, leaving
+///         veVirtual's raw `approve()` allowance (L345) standing after the call returns.
+///         Distinct from MaliciousConverterMock (H-4), which DOES pull funds via transferFrom
+///         and therefore leaves zero residual allowance.
+contract NoOpConverterMock is IRVirtualConverter {
+    address public virtualToken;
+
+    constructor(address virtualToken_) {
+        virtualToken = virtualToken_;
+    }
+
+    function convertVirtualToRVirtual(
+        uint256 /* amount */,
+        address /* rVirtualReceiver */
+    ) external override {
+        // Intentionally does nothing - no transferFrom, no revert.
+    }
+}

contracts/token/mocks/RVirtualConverterV2Mock.sol

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "../RVirtualConverter.sol";
+
+/// @notice Test-only V2 used to verify RVirtualConverter's UUPS upgrade path round-trips
+///         cleanly. Adds one new event + trigger function on top of V1; never deployed to
+///         production - exists purely so a test can upgrade forward, prove the new code is
+///         live, then upgrade back and confirm the final bytecode matches the original V1.
+contract RVirtualConverterV2Mock is RVirtualConverter {
+    event V2UpgradeMarker(string message);
+
+    function triggerV2Marker() external {
+        emit V2UpgradeMarker("upgraded");
+    }
+}

contracts/token/veVirtual.sol

@@ -7,6 +7,7 @@ import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import "@openzeppelin/contracts/utils/structs/Checkpoints.sol";
 import "@openzeppelin/contracts-upgradeable/governance/utils/VotesUpgradeable.sol";
+import "./IRVirtualConverter.sol";
 
 contract veVirtual is
     Initializable,
@@ -34,6 +35,11 @@ contract veVirtual is
 
     uint8 public maxWeeks;
 
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor() {
+        _disableInitializers();
+    }
+
     event Stake(
         address indexed user,
         uint256 id,
@@ -47,6 +53,14 @@ contract veVirtual is
     event AdminUnlocked(bool adminUnlocked);
     bool public adminUnlocked;
 
+    address public rVirtualConverter;
+    event RVirtualConverterUpdated(address rVirtualConverter);
+    event ConvertedVeVirtualToRVirtual(
+        address indexed user,
+        uint256 id,
+        uint256 amount
+    );
+
     function initialize(
         address baseToken_,
         uint8 maxWeeks_
@@ -298,4 +312,52 @@ contract veVirtual is
         }
         return amount;
     }
+
+    /**
+     * @notice Set the RVirtualConverter contract that convertVeVirtualToRVirtual() forwards to.
+     */
+    function setRVirtualConverter(
+        address rVirtualConverter_
+    ) external onlyRole(ADMIN_ROLE) {
+        require(rVirtualConverter_ != address(0), "Invalid converter");
+        require(
+            IRVirtualConverter(rVirtualConverter_).virtualToken() == baseToken,
+            "Converter token mismatch"
+        );
+        rVirtualConverter = rVirtualConverter_;
+        emit RVirtualConverterUpdated(rVirtualConverter_);
+    }
+
+    /**
+     * @notice Voluntarily give up a lock's underlying VIRTUAL (and its voting power) in
+     *         exchange for an equal amount of rVirtual. Unlike withdraw(), this does not
+     *         require the lock to be matured - the user is explicitly forfeiting the
+     *         remaining lock time. The lock is deleted regardless of its autoRenew state.
+     * @dev Approves RVirtualConverter for exactly this lock's amount and calls its
+     *      convertVirtualToRVirtual() - the same open entrypoint any wallet can call directly.
+     *      There is no veVirtual-specific path on the converter side.
+     */
+    function convertVeVirtualToRVirtual(uint256 id) external nonReentrant {
+        require(rVirtualConverter != address(0), "Converter not set");
+        address account = _msgSender();
+        uint256 index = _indexOf(account, id);
+        Lock memory lock = locks[account][index];
+
+        uint256 amount = lock.amount;
+
+        uint256 lastIndex = locks[account].length - 1;
+        if (index != lastIndex) {
+            locks[account][index] = locks[account][lastIndex];
+        }
+        locks[account].pop();
+
+        IERC20(baseToken).forceApprove(rVirtualConverter, amount);
+        IRVirtualConverter(rVirtualConverter).convertVirtualToRVirtual(
+            amount,
+            account
+        );
+
+        emit ConvertedVeVirtualToRVirtual(account, id, amount);
+        _transferVotingUnits(account, address(0), amount);
+    }
 }