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,22 @@
+// 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);
+
+    /// @notice The rVirtual token this converter pays out. Exposed so callers (e.g.
+    ///         veVirtual.setRVirtualConverter) can snapshot the expected payout token at
+    ///         wiring time and verify actual delivery against their OWN stored copy later,
+    ///         rather than trusting whatever the converter claims to pay out at conversion
+    ///         time - the converter is separately upgradeable, so that claim could change
+    ///         without a re-wiring call (see audit H-1 / M-02).
+    function rVirtualToken() external view returns (address);
+}

contracts/token/RVirtualConverter.sol

@@ -0,0 +1,105 @@
+// 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";
+import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.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");
+        // The 1:1 conversion below is a raw-integer transfer with no decimals rescaling -
+        // only correct when both tokens use the same decimals (18, by protocol design).
+        // Asserted here (audit I-03) rather than left as a comment, since a future
+        // deployment of this converter against a different pair would otherwise mis-scale
+        // every conversion silently.
+        require(
+            IERC20Metadata(virtualToken_).decimals() == IERC20Metadata(rVirtualToken_).decimals(),
+            "Decimals mismatch"
+        );
+        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,33 @@
+// 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 rVirtualToken;
+    address public immutable attacker;
+
+    constructor(address virtualToken_, address rVirtualToken_, address attacker_) {
+        virtualToken = virtualToken_;
+        rVirtualToken = rVirtualToken_;
+        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,27 @@
+// 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;
+    address public rVirtualToken;
+
+    constructor(address virtualToken_, address rVirtualToken_) {
+        virtualToken = virtualToken_;
+        rVirtualToken = rVirtualToken_;
+    }
+
+    function convertVirtualToRVirtual(
+        uint256 /* amount */,
+        address /* rVirtualReceiver */
+    ) external override {
+        // Intentionally does nothing - no transferFrom, no revert.
+    }
+}

contracts/token/mocks/NonConsumingConverterMock.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 for the audit I-04 regression test. Delivers the correct rVirtual
+///         amount from its own pre-funded balance (so the M-02 delivery check passes and the
+///         call does not revert), but never calls transferFrom on the approved VIRTUAL -
+///         simulating a converter that pays out correctly through some path that doesn't
+///         consume veVirtual's allowance. This is the only way, once the M-02 balance-delta
+///         check is in place, to reach a *successful* conversion that still leaves the
+///         allowance standing - a plain no-op or fund-stealing converter now reverts the
+///         whole transaction instead (see MaliciousConverterMock / NoOpConverterMock).
+contract NonConsumingConverterMock is IRVirtualConverter {
+    address public virtualToken;
+    address public rVirtualToken;
+
+    constructor(address virtualToken_, address rVirtualToken_) {
+        virtualToken = virtualToken_;
+        rVirtualToken = rVirtualToken_;
+    }
+
+    function convertVirtualToRVirtual(
+        uint256 amount,
+        address rVirtualReceiver
+    ) external override {
+        // Deliver from this contract's own balance - never touches the VIRTUAL allowance.
+        IERC20(rVirtualToken).transfer(rVirtualReceiver, amount);
+    }
+}

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");
+    }
+}