Merge branch 'rename-euler-swap'

Author: euler-mab

README.md

@@ -1,101 +1,80 @@
-# Euler Maglev
+# Euler Swap
 
-![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 actual liquidity.
+EulerSwap is an Automated Market Maker (AMM) that uses [Euler Vaults](https://docs.euler.finance/euler-vault-kit-white-paper/) as leveraged lending products in order to extend the range of its reserves and thereby improve the capital efficiency of liquidity provisioning.
 
 To swappers, Maglev presents a hopefully familiar Uniswap2-style interface but internally it supports borrow and repaying, custom pricing curves, and other advanced functionality. Although useable by anyone, it is primarily intended to be invoked by sophisticated actors such as swap aggregators, intents solvers, and MEV bots. Similar to Uniswap, there is a careful separation between the critical core functionality for servicing swaps and the surrounding periphery functions for quoting, etc.
 
 <!-- TOC FOLLOWS -->
 <!-- START OF TOC -->
 <!-- DO NOT EDIT! Auto-generated by md-toc: https://github.com/hoytech/md-toc -->
 
-* [Concept](#concept)
-* [Operation](#operation)
-    * [Usage](#usage)
-    * [Reconfiguration](#reconfiguration)
-    * [Debt Limits](#debt-limits)
-    * [Desynchronised Reserves](#desynchronised-reserves)
-    * [Fees](#fees)
-* [EulerSwap Curve](#eulerswap-curve)
-* [See Also](#see-also)
-    * [Prior Art](#prior-art)
-* [License](#license)
+- [Concept](#concept)
+- [Operation](#operation)
+  - [Usage](#usage)
+  - [Virtual Reserves](#virtual-reserves)
+  - [Desynchronised Virtual Reserves](#desynchronised-virtual-reserves)
+- [Curves](#curves)
+  - [Constant Sum](#constant-sum)
+  - [Constant Product](#constant-product)
+- [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, their "in token" repays the loan and the excess collateral is sent as the "out token", thereby unwinding the position.
+Given a fixed size investment, EulerSwap 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, the loan can be repaid in exchange for receiving the collateral, unwinding the borrow 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 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 (occasionally even going negative) by taking advantage of incentives such as points/rewards.
 
 ## Operation
 
-Since the level of acceptable borrowing risk is not necessarily the same for every user, pooled deposits are not supported. Each Maglev instance manages funds for a single entity (which of course may be jointly owned).
+Since the level of acceptable borrowing risk may not be the same for every user, pooled deposits are not yet possible, and each EulerSwap instance manages funds for a single user (who of course may operate on behalf of pooled funds).
 
-Maglev is a contract designed to be used as an [EVC operator](https://evc.wtf/docs/whitepaper/#operators). This means that the user, known as the *holder*, does not give up control over their funds to a smart contract, but instead retains it in their wallet. The holder can be any compatible address, including standard multisig wallets or even an EOA.
+EulerSwap is a contract designed to be used as an [EVC operator](https://evc.wtf/docs/whitepaper/#operators). This means that the user, known as the _holder_, does not give up control over their funds to a smart contract, but instead retains it in their wallet. The holder can be any compatible address, including standard multisig wallets or even an EOA.
 
 ### Usage
 
-The following are the high-level steps required to setup Maglev:
-
-* Deposit funds into one or both of the vaults in proportion to the initial price
-* Deploy the desired Maglev contract, choosing parameters such as the vaults, initial price ratio, debt limits, and the swapping 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
-* Optional: Invoke the `activate()` function on the Maglev contract. Otherwise, Maglev will be activated when the first swap is performed (increasing its gas cost somewhat)
+The following are the high-level steps required to use EulerSwap:
 
-### Reconfiguration
+- Deposit funds into one or both of the vaults
+- Deploy the desired EulerSwap contract, choosing parameters such as the vaults and the desired `fee`
+- Calculate the desired [virtual reserves](#virtual-reserves) and set these values by invoking `setVirtualReserves()`
+- Install the EulerSwap contract as an operator for your account
+- Invoke the `configure()` function on the EulerSwap contract
 
-All user-configurable parameters are stored in immutable variables, meaning they cannot be changed after the AMM is deployed. Instead, the holder should uninstall it from its EVC operator set, and a new Maglev instance should be created and installed in its place.
+At this point, anyone can invoke `swap()` on the EulerSwap contract, and this will perform borrowing and transferring activity between the two vaults.
 
 ### 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 immediate losses 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 amount currently held in reserve.
+The initial deposits in the vaults represent the initial investment, and are swapped back and forth in response to swapping activity. In a conventional AMM such as Uniswap, these balance are called _reserves_. However, if swapping was constrained to these assets alone, then this would imply a hard limit on the size of swaps that can be serviced. To increase the effective funds, EulerSwap AMMs are configured with _virtual reserves_. These are typically larger than the size of the conventional reserves, which signifies that not only can all the assets be swapped from one vault to another, but even more assets can be borrowed on the EulerSwap's account.
 
-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.
+Virtual reserves control the maximum debt that the EulerSwap contract will attempt to acquire on each of its two vaults. Each vault can be configured independently.
 
-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.
+For example, if the initial investment has a NAV of $1000, and virtual reserves are configured at $5000 for each vault, 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 select 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. 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 the the maximum LTV cannot actually be achieved because of the design of the curve. Instead, it will only approach these reserve levels asymptotically, since each unit gets more and more expensive.
+Note that it depends on the [curve](#curves) if the maximum LTV can actually be achieved. A constant product will only approach these reserve levels asymptotically, since each unit will get more and more expensive. However, with constant sum, this LTV can be achieved directly.
 
 ### Desynchronised Reserves
 
-The Maglev contract tracks what it believes the reserves (balance 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 (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
-
-Maglev collects swap fees in the input token. In the core, after depositing but prior to verifying the curve invariant, all input amounts are adjusted down (rounding down).
-
-In the periphery, when quoting exact input swaps the effective input amount is decreased by the fee (rounding down) before consulting the curve. When quoting exact output swaps, the required input amount is increased by the fee (rounding up).
-
-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, and compounding of these proceeds is desired, the Maglev instance should be [replaced](#desynchronised-reserves) by an instance with higher debt limits.
-
-
-## EulerSwap Curve
+The EulerSwap contract tracks what it believes the reserves to be by caching their values in storage. These reserves are updated on each swap. However, since the balance is not actually held by the EulerSwap contract (it is simply an operator), the actual underlying balances may get out of sync. This can happen gradually as interest is accrued, or suddenly if the holder moves funds or the position is liquidated.
 
-Although the Maglev interface can support various types of curves, the current implementation only uses the *EulerSwap curve*. This is a new curve developed by Euler Labs, and 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.
+When this occurs, the `syncVirtualReserves()` should be invoked. This determines the actual balances (and debts) of the holder, and adjusts them by the configured virtual reserve levels.
 
-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 resembles a constant sum, and the lower (closer to 0), a constant product. The curve is also parameterised by a `price` 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.
+## Curves
 
-With careful parameter selection, the EulerSwap curve supports optimal tradeoffs between capital efficiency and arbitrage incentives.
+### Constant Sum
 
+This "curve" simply adds the values of the two reserves together and ensures that after a swap this sum has not decreased. This curve is mostly suitable for assets that are pegged to the same value, such as stable/stable pairs.
 
-## See Also
+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.
 
-### Prior Art
+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 fees for swaps of any allowed size (fixed price impact).
 
-* [Blackhole swap](https://blackholeswap.com/documents/en.pdf): Essentially the same concept, but using a less optimal curve and hardcoded to two Compound pools.
+### Constant Product
 
+This is the traditional Uniswap2 curve that preserves the product of the two reserves. The larger a swap, the higher the price impact and the more profitable it is to arbitrage a disbalanced pool back to its wider market price.
 
 ## License