docs

Author: hoytech

README.md

@@ -2,9 +2,9 @@
 
 ![Maglev logo](docs/maglev.png)
 
-Maglev is an Automated Market Maker (AMM) that uses [Euler Vaults](https://docs.euler.finance/euler-vault-kit-white-paper/) to *mag*nify capital efficiency using *lev*erage. By borrowing assets as needed, Maglev AMMs can extend the range of their reserves and earn fees on trades several times larger than their liquidity outlay.
+Maglev is an Automated Market Maker (AMM) that uses [Euler Vaults](https://docs.euler.finance/euler-vault-kit-white-paper/) to **mag**nify capital efficiency using **lev**erage. By borrowing assets as needed, Maglev AMMs can extend the range of their reserves and earn fees on trades several times larger than their actual liquidity.
 
-To swappers, Maglev presents a conventional Uniswap2-style interface but internally it supports custom pricing curves and other advanced functionality. Although useable by anyone, the primary swapper user-base is intended to be aggregators, intents solvers, and MEV bots.
+To swappers, Maglev presents a conventional Uniswap2-style interface but internally it supports borrow and repaying, custom pricing curves, and other advanced functionality. Although invokeable by anyone, the primary swapper user-base is intended to be aggregators, intents solvers, and MEV bots.
 
 <!-- TOC FOLLOWS -->
 <!-- START OF TOC -->
@@ -22,17 +22,19 @@ To swappers, Maglev presents a conventional Uniswap2-style interface but interna
     * [Constant Product](#constant-product)
     * [EulerSwap Curve](#eulerswap-curve)
 * [Todo](#todo)
+* [See Also](#see-also)
+    * [Prior Art](#prior-art)
 * [License](#license)
 
 <!-- END OF TOC -->
 
 ## Concept
 
-Given a fixed size investment, Maglev aims to increase the size of trades that can be serviced relative to a conventional AMM such as Uniswap. It does this by borrowing the "out token" and collateralising this loan with the received "in token". Later on, when somebody wishes to swap in the reverse direction, they repay the loan and receive the excess collateral, unwinding the borrow position.
+Given a fixed size investment, Maglev aims to increase the size of trades that can be serviced relative to a conventional AMM such as Uniswap. It does this by borrowing the "out token" and collateralising this loan with the received "in token". Later on, when somebody wishes to swap in the reverse direction, their "in token" repays the loan and the excess collateral is sent as the "out token", thereby unwinding the position.
 
-Because the total size of the position can be many times larger than the initial investment (depending on how much LTV/leverage is allowed on the underlying lending pools), the swap fees earned can be magnified.
+Because the total size of the position can be many times larger than the initial investment (depending on how much LTV/leverage is allowed on the underlying lending pools), the swap fees earned are multiplied.
 
-The down-side is that while the AMM holds this leveraged position, it is paying interest on the loan. Fortunately, this is partially compensated by the fact that the AMM is simultaneously earning interest on the collateral. In some cases, this interest rate spread can be reduced further by taking advantage of incentives such as points/rewards.
+The down-side is that while the AMM holds this leveraged position, it is paying interest on the loan. Fortunately, this is partially compensated by the fact that the AMM is simultaneously earning interest on the collateral. In some cases, this interest rate spread can be reduced further (occasionally even going negative) by taking advantage of incentives such as points/rewards.
 
 ## Operation
 
@@ -46,7 +48,7 @@ The following are the high-level steps required to use Maglev:
 
 * Deposit funds into one or both of the vaults in proportion of the initial price
 * 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 debt and balances to setup its reserves cache
+  * 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
   * This function can be invoked by anyone, and it is harmless to re-invoke it
@@ -55,27 +57,27 @@ At this point, anyone can invoke `swap()` on the Maglev contract, and this will
 
 ### Reconfiguration
 
-All user-configurable parameters are stored in immutable variables, meaning they cannot be changed after the AMM is deployed. Instead, the holder should be uninstalled it from its EVC operator set, and a new Maglev instance should be created and installed in its place.
+All user-configurable parameters are stored in immutable variables, meaning they cannot be changed after the AMM is deployed. Instead, the holder should uninstalled it from its EVC operator set, and a new Maglev instance should be created and installed in its place.
 
 ### Debt Limits
 
 The initial deposits in the two vaults represent the initial investment, and are swapped back and forth in response to swapping activity. In order to prevent loss to arbitrage, the initial investment should be made in proportion to the price of the assets.
 
-In a conventional AMM such as Uniswap, the balances held by the contract are called *reserves*, and these represent a hard upper-bound on the amounts that can be swapped: In other words, no matter how much you are willing to pay, you can never receive more than the current reserve.
+In a conventional AMM such as Uniswap, the balances held by the contract are called *reserves*, and these represent a hard upper-bound on the amounts that can be swapped: In other words, no matter how much you are willing to pay, you can never receive more than the amount currently held in reserve.
 
 To increase the effective swappable amounts, not only will Maglev AMMs swap all their reserves, but they will internally borrow *more* of the desired token in order to service a swap. How much debt the AMM is willing to take depends on the configured debt limits.
 
 For example, if the initial investment has a NAV of $1000, and the debt limit is configured at $5000, then the maximum LTV loan that the AMM will support will be `5000/6000 = 0.8333`. In order to leave a safety buffer, it is recommended to choose a maximum LTV that is below the borrowing LTV of the vault.
 
-Each vault can have its own independent debt limit, which may be useful in case of vaults configured with asymmetric LTVs.
+Each vault can have its own independent debt limit, which may be useful in case of vaults configured with asymmetric LTVs. A debt limit of 0 could be specified for one of the vaults if the holder only ever wants a borrow position in one of the assets. In the future we may add a debt minimum, allowing the holder to retain a position within a certain leverage range while continuing to profit off swapping activity.
 
 Note that it depends on the [curve](#curves) if the maximum LTV can actually be achieved. A constant product curve will only approach these reserve levels asymptotically, since each unit will get more and more expensive. With a constant sum curve, the LTV can be achieved precisely.
 
 ### Desynchronised Reserves
 
 The Maglev contract tracks what it believes the reserves (amount available plus borrowable) to be by caching in storage. These reserves are updated on each swap. However, since the balance is not actually held by the Maglev contract (it is simply an operator), the actual underlying debts and balances may get out of sync. This can happen gradually as interest and fees are accrued, or suddenly if the holder moves funds or the position is liquidated.
 
-Normally this is not a problem, because swapping will still occur on the static curve. However, if there is a significant decrease in NAV then the desired LTVs may be exceeded (since the debt limit becomes higher relative to the NAV). If there is a significant increase in NAV then the AMM may become less capital efficient. To reset this, the Maglev instance should be uninstalled as an EVC operator, and a new one created and installed in its place.
+Normally this is not a problem, because swapping will still occur on the static curve (such actions do not change the offered prices). However, if there is a significant decrease in NAV then the desired LTVs may be exceeded (since the debt limit becomes higher relative to the NAV). If there is a significant increase in NAV then the AMM may become less capital efficient. To resynchronise, the Maglev instance should be uninstalled as an EVC operator, and a new one created and installed in its place.
 
 ### Fees
 
@@ -85,7 +87,7 @@ When quoting exact input swaps the effective input amount is decreased by the fe
 
 After depositing but prior to verifying the curve invariant, all input amounts are adjusted down (rounding down).
 
-Since the full amount including fees is actually deposited (or repayed), fees have the effect of increasing the NAV of the position. However, they are not currently "fed back" into the reserves to be used by future swaps. If fees build up significantly, the Maglev instance should be [replaced](#desynchronised-reserves).
+Since the full amount including fees is actually deposited (or repaid), fees have the effect of increasing the NAV of the position. However, they are not currently "fed back" into the reserves to be used by future swaps. If fees build up significantly, the Maglev instance should be [replaced](#desynchronised-reserves).
 
 
 ## Curves
@@ -96,7 +98,7 @@ This "curve" simply adds the values of the two reserves together and ensures tha
 
 This curve supports a price fraction so that the two tokens can have different relative values, which can be useful if the peg is other than 1:1, or if the tokens have differing decimals.
 
-In this curve, the entire virtual reserves can be consumed, and since each marginal unit of the swap has the same price, there is no direct incentive to deleverage the position. However, for the same reason this does allow fixed-size fees for swaps of any supported size (fixed price impact).
+In this curve, the entire virtual reserves can be consumed, and since each marginal unit of the swap has the same price, there is no direct incentive for arbitrageurs to deleverage the position. However, for the same reason this does allow fixed-size fees for swaps of any supported size (fixed price impact).
 
 ### Constant Product
 
@@ -106,7 +108,7 @@ This is the traditional Uniswap2 curve that preserves the product of the two res
 
 This is a new curve developed by Euler. It can be thought of as a hybrid between constant sum and constant product. The curve is defined piecewise: A piece to the left of an "initial reserves" point, and a piece to the right.
 
-Each piece has a `concentration` parameter that determines the trade-off between constant sum and constant product. The higher the concentration (closer to 1), the more it is similar to a constant sum, and the lower (closer to 0), constant product. The curve is also parameterise by a `price` parameter which determines the slope at the initial reserves point. There are actually two price parameters which can be considered the numerator and denominator of the price fraction.
+Each piece has a `concentration` parameter that determines the trade-off between constant sum and constant product. The higher the concentration (closer to 1), the more it is similar to a constant sum, and the lower (closer to 0), a constant product. The curve is also parameterised by a `price` parameter which determines the slope at the initial reserves point. There are actually two price parameters which can be considered the numerator and denominator of the price fraction.
 
 With careful parameter selection, the EulerSwap curve supports optimal tradeoffs between capital efficiency and arbitrage incentives.
 
@@ -115,15 +117,15 @@ With careful parameter selection, the EulerSwap curve supports optimal tradeoffs
 ## Todo
 
 * The EulerSwap curve has some numerical instability that we believe is caused by rounding
-  * We think the biggest effect is that it may cause some swaps to fail even if the the quoted amount is provided. Also, it may result in users slightly overpaying for swaps.
+  * We think the biggest effect is that it may cause some swaps to fail even if the exact quoted amount is sent. Also, it may result in users slightly overpaying for swaps.
   * The code currently has a roundingCompensation adjustment that seems to prevent this, but since we don't know a hard upper-bound it's hard to say if this solves it in all cases
 * Currently we have only been supporting stable-stable pairs
   * What extra considerations would there be for floating pairs?
 * Automatically re-invest fees. There are a few options:
   * Don't do anything: Re-deploing probably isn't a huge deal
   * Increase the reserves by the fee amount
   * Increase the reserves by the extra amount of possible leverage supported by the new fee
-  * Apply fees to a super-concentrated section of the curve (needs R&D)
+  * Apply fees to a super-concentrated middle section of the curve (needs R&D)
 * Could current reserves be calculated dynamically based on balances/debts/debt limits?
   * I guess you would lose a chunk of interest to arbitrage
   * Donation attacks?
@@ -134,6 +136,13 @@ With careful parameter selection, the EulerSwap curve supports optimal tradeoffs
 * Other misc stuff (see `TODO` file)
 
 
+## See Also
+
+### Prior Art
+
+* [Blackhole swap](https://blackholeswap.com/documents/en.pdf): Essentially the same concept, but using a less optimal curve and hardcoded to two Compound pools.
+
+
 ## License
 
 (c) 2024 Euler Labs Ltd.