Merge branch 'master' into feat/factory

Author: haythemsellami

.DS_Store

@@ -16,7 +16,7 @@ jobs:
     name: Foundry project
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
         with:
           submodules: recursive
 
@@ -36,7 +36,7 @@ jobs:
 
       - name: Run Forge build
         run: |
-          forge build --sizes
+          forge build --force --skip test --sizes
         id: build
 
       - name: Run Forge tests

.github/workflows/test.yml

@@ -1,150 +1,67 @@
-# Euler Maglev
+# EulerSwap
 
-![Maglev logo](docs/maglev.png)
+EulerSwap is an Automated Market Maker (AMM) that uses [Euler lending 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.
 
-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, EulerSwap 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.
 
-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.
+For more information, refer to the [white paper](./docs/white-paper/EulerSwap_White_Paper.pdf).
 
-<!-- TOC FOLLOWS -->
-<!-- START OF TOC -->
-<!-- DO NOT EDIT! Auto-generated by md-toc: https://github.com/hoytech/md-toc -->
+## Usage
 
-* [Concept](#concept)
-* [Operation](#operation)
-    * [Usage](#usage)
-    * [Reconfiguration](#reconfiguration)
-    * [Debt Limits](#debt-limits)
-    * [Desynchronised Reserves](#desynchronised-reserves)
-    * [Fees](#fees)
-* [Curves](#curves)
-    * [Constant Sum](#constant-sum)
-    * [Constant Product](#constant-product)
-    * [EulerSwap Curve](#eulerswap-curve)
-* [Todo](#todo)
-* [See Also](#see-also)
-    * [Prior Art](#prior-art)
-* [License](#license)
+EulerSwap comes with a comprehensive set of tests written in Solidity, which can be executed using Foundry.
 
-<!-- END OF TOC -->
+To install Foundry:
 
-## Concept
+```sh
+curl -L https://foundry.paradigm.xyz | bash
+```
 
-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.
+This will download foundryup. To start Foundry, run:
 
-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.
+```sh
+foundryup
+```
 
-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.
+To clone the repo:
 
-## Operation
+```sh
+git clone https://github.com/euler-xyz/euler-swap.git && cd euler-swap
+```
 
-Since the level of acceptable borrowing risk is not be the same for every user, pooled deposits are not supported. Each Maglev instance manages funds for a single entity (who of course may be jointly owned).
+## Testing
 
-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.
+### in `default` mode
 
-### Usage
+To run the tests in a `default` mode:
 
-The following are the high-level steps required to use Maglev:
+```sh
+forge test
+```
 
-* 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 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
+### in `coverage` mode
 
-At this point, anyone can invoke `swap()` on the Maglev contract, and this will perform borrowing and transferring activity between the two vaults.
+```sh
+forge coverage
+```
 
-### Reconfiguration
+## Safety
 
-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.
+This software is experimental and is provided "as is" and "as available".
 
-### Debt Limits
+No warranties are provided and no liability will be accepted for any loss incurred through the use of this codebase.
 
-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.
+Always include thorough tests when using EulerSwap to ensure it interacts correctly with your code.
 
-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.
+## Known limitations
 
-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.
+Refer to the [white paper](./docs/white-paper/EulerSwap_White_Paper.pdf) for a list of known limitations and security considerations.
 
-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. 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 (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.
-
-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).
-
-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 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
-
-### Constant Sum
-
-This "curve" simply adds the values of the two reserves together and ensures that after a swap this sum has not decreased. It is mostly suitable for assets that are pegged to the same value, such as stable-stable pairs.
-
-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 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
-
-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 the market price.
-
-### EulerSwap Curve
-
-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), 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.
-
-
-
-## 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 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 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?
-* What can we do to make this easily integrated with aggregators/MEV bots/etc?
-  * For sure we need events. What should be logged?
-  * How to handle a discovery/tracking of the different Maglev instances?
-    * Factory? Registry? Maybe a fake factory that reads the actually installed operators from a set of addresses?
-* 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.
+## Contributing
 
+The code is currently in an experimental phase. Feedback or ideas for improving EulerSwap are appreciated. Contributions are welcome from anyone interested in conducting security research, writing more tests including formal verification, improving readability and documentation, optimizing, simplifying, or developing integrations.
 
 ## License
 
-(c) 2024 Euler Labs Ltd.
+(c) 2024-2025 Euler Labs Ltd.
 
 All rights reserved.

README.md

@@ -0,0 +1,8 @@
+# Security policy
+
+## Reporting a vulnerability
+
+If you discover a security vulnerability, please report it responsibly. Do not publicly disclose the issue until your report has been addressed. Resources for reporting:
+
+- **Email:** [email protected]
+- **Further reading:** https://docs.euler.finance/security/overview