some cleanup and natspec

Author: hoytech

README.md

@@ -50,7 +50,7 @@ The following are the high-level steps required to use Maglev:
 * Deploy the desired Maglev contract, choosing parameters such as the vaults, debt limits, and the desired `fee`
   * Note that the Maglev contract must be created after the funds are deposited, because its constructor will read the current debts and balances to setup its reserves cache
 * Install the Maglev contract as an operator for your account
-* Invoke the `configure()` function on the Maglev contract
+* Invoke the `activate()` function on the Maglev contract
   * This function can be invoked by anyone, and it is harmless to re-invoke it
 
 At this point, anyone can invoke `swap()` on the Maglev contract, and this will perform borrowing and transferring activity between the two vaults.

src/MaglevBase.sol

@@ -15,8 +15,8 @@ abstract contract MaglevBase is IMaglevBase, EVCUtil {
     address public immutable myAccount;
     uint256 public immutable feeMultiplier;
 
-    uint112 internal reserve0;
-    uint112 internal reserve1;
+    uint112 public reserve0;
+    uint112 public reserve1;
     uint32 internal locked; // uses single storage slot, accessible via getReserves()
 
     error Locked();
@@ -80,8 +80,10 @@ abstract contract MaglevBase is IMaglevBase, EVCUtil {
 
     // Owner functions
 
-    /// @dev Call *after* installing as operator
-    function configure() external {
+    /// @notice Approve the vaults to access the Maglev instance's tokens,
+    /// and enables vaults as collateral. Must call *after* installing
+    /// the Maglev instance as an operator.
+    function activate() external {
         IERC20(asset0).approve(vault0, type(uint256).max);
         IERC20(asset1).approve(vault1, type(uint256).max);
 
@@ -91,6 +93,10 @@ abstract contract MaglevBase is IMaglevBase, EVCUtil {
 
     // Swapper interface
 
+    /// @notice Optimistically sends the requested amounts of tokens to the `to`
+    /// address, invokes `uniswapV2Call` callback on `to` (if `data` provided), and
+    /// then verifies that a sufficient amount of tokens were transferred to
+    /// satisfy the swapping curve invariant.
     function swap(uint256 amount0Out, uint256 amount1Out, address to, bytes calldata data)
         external
         callThroughEVC
@@ -137,16 +143,19 @@ abstract contract MaglevBase is IMaglevBase, EVCUtil {
         }
     }
 
+    /// @notice Convenience function for when both reserve values are needed.
     function getReserves() public view returns (uint112, uint112, uint32) {
         return (reserve0, reserve1, locked);
     }
 
+    /// @notice How much `tokenOut` can I get for `amountIn` of `tokenIn`?
     function quoteExactInput(address tokenIn, address tokenOut, uint256 amountIn) external view returns (uint256) {
-        return _computeQuote(tokenIn, tokenOut, amountIn, true);
+        return computeFullQuote(tokenIn, tokenOut, amountIn, true);
     }
 
+    /// @notice How much `tokenIn` do I need to get `amountOut` of `tokenOut`?
     function quoteExactOutput(address tokenIn, address tokenOut, uint256 amountOut) external view returns (uint256) {
-        return _computeQuote(tokenIn, tokenOut, amountOut, false);
+        return computeFullQuote(tokenIn, tokenOut, amountOut, false);
     }
 
     // Internal utilities
@@ -205,7 +214,9 @@ abstract contract MaglevBase is IMaglevBase, EVCUtil {
         }
     }
 
-    function _computeQuote(address tokenIn, address tokenOut, uint256 amount, bool exactIn)
+    /// @dev This function handles quoting, including swap fees. Curve-specific
+    /// quote calculations are delegated to computeQuote().
+    function computeFullQuote(address tokenIn, address tokenOut, uint256 amount, bool exactIn)
         internal
         view
         returns (uint256)
@@ -236,8 +247,10 @@ abstract contract MaglevBase is IMaglevBase, EVCUtil {
         return quote;
     }
 
-    /// @dev May be overridden by subclass if there is a more efficient method
-    /// of computing quotes than binary search.
+    /// @dev This function generates quotes given the specific installed curve
+    /// instance. The base-class implementation is a binary search, however this
+    /// may be overridden by a subclass if there is a more efficient method
+    /// of computing quotes, or if a curve is non-convex.
     function computeQuote(uint256 amount, bool exactIn, bool asset0IsInput)
         internal
         view
@@ -281,6 +294,9 @@ abstract contract MaglevBase is IMaglevBase, EVCUtil {
         }
     }
 
-    /// @dev Must be implemented by sub-class
+    /// @dev Function that defines the shape of the swapping curve. Returns true iff
+    /// the provided reserve amounts are acceptable to the pool. Geometrically, this
+    /// can be visualised as checking if a point is on or above/to the right of
+    /// the swapping curve. This function must be implemented by a sub-class.
     function verify(uint256 newReserve0, uint256 newReserve1) internal view virtual returns (bool);
 }

src/MaglevEulerSwap.sol

@@ -32,7 +32,7 @@ contract MaglevEulerSwap is IMaglevEulerSwap, MaglevBase {
         initialReserve1 = reserve1;
     }
 
-    function fx(uint256 xt, uint256 px, uint256 py, uint256 x0, uint256 y0, uint256 c)
+    function f(uint256 xt, uint256 px, uint256 py, uint256 x0, uint256 y0, uint256 c)
         internal
         pure
         returns (uint256)
@@ -43,10 +43,10 @@ contract MaglevEulerSwap is IMaglevEulerSwap, MaglevBase {
     function verify(uint256 newReserve0, uint256 newReserve1) internal view virtual override returns (bool) {
         if (newReserve0 >= initialReserve0) {
             if (newReserve1 >= initialReserve1) return true;
-            return newReserve0 >= fx(newReserve1, priceY, priceX, initialReserve1, initialReserve0, concentrationY);
+            return newReserve0 >= f(newReserve1, priceY, priceX, initialReserve1, initialReserve0, concentrationY);
         } else {
             if (newReserve1 < initialReserve1) return false;
-            return newReserve1 >= fx(newReserve0, priceX, priceY, initialReserve0, initialReserve1, concentrationX);
+            return newReserve1 >= f(newReserve0, priceX, priceY, initialReserve0, initialReserve1, concentrationX);
         }
     }
 }

src/interfaces/IMaglevBase.sol

@@ -2,7 +2,7 @@
 pragma solidity >=0.8.0;
 
 interface IMaglevBase {
-    function configure() external;
+    function activate() external;
     function swap(uint256 amount0Out, uint256 amount1Out, address to, bytes calldata data) external;
     function quoteExactInput(address tokenIn, address tokenOut, uint256 amountIn) external view returns (uint256);
     function quoteExactOutput(address tokenIn, address tokenOut, uint256 amountOut) external view returns (uint256);

test/ConstantProduct.t.sol

@@ -27,7 +27,7 @@ contract ConstantProductTest is MaglevTestBase {
         evc.setAccountOperator(holder, address(maglev), true);
 
         vm.prank(anyone);
-        maglev.configure();
+        maglev.activate();
     }
 
     function test_basicExactIn() public monotonicHolderNAV {

test/ConstantSum.t.sol

@@ -31,7 +31,7 @@ contract ConstantSumTest is MaglevTestBase {
         evc.setAccountOperator(holder, address(maglev), true);
 
         vm.prank(anyone);
-        maglev.configure();
+        maglev.activate();
     }
 
     function test_basicSwapReport() public monotonicHolderNAV {

test/EulerSwap.t.sol

@@ -38,7 +38,7 @@ contract EulerSwapTest is MaglevTestBase {
         evc.setAccountOperator(holder, address(maglev), true);
 
         vm.prank(anyone);
-        maglev.configure();
+        maglev.activate();
     }
 
     function test_different_EVC() public {

test/PreserveNav.t.sol

@@ -36,7 +36,7 @@ contract PreserveNav is MaglevTestBase {
         evc.setAccountOperator(holder, address(maglev), true);
 
         vm.prank(anyone);
-        maglev.configure();
+        maglev.activate();
     }
 
     function test_preserve_nav(

test/UniswapV2Call.t.sol

@@ -37,7 +37,7 @@ contract UniswapV2CallTest is MaglevTestBase {
         evc.setAccountOperator(holder, address(maglev), true);
 
         vm.prank(anyone);
-        maglev.configure();
+        maglev.activate();
     }
 
     function test_callback() public {