|
| 1 | +# Liquidity Pool |
| 2 | +- this is my personal implementation of decnetralized exchange using Liquidy Pool and Swaps inspired by Uniswap V2 (reference)[https://uniswap.org/blog/uniswap-v2]. |
| 3 | +- The main difference is that my code is only meant to swap ETH with one Token (called `SPC`), while in Uniswap, it is possible to Swap with any number of combinations. Also, uniswap has flash swaps (for trading bots) while I opted to leave this out to reduce complexity a bit. |
| 4 | +- generally speaking I made the logic more verbose so it's easier to understand for me and for auditors so keep in mind that I preferred readability over gas savings. |
| 5 | +- I did my best to simplify uniswap concepts by writing out the constant product formulas, geometric mean, etc in an easy to read way |
| 6 | + |
| 7 | +## Main Commands |
| 8 | + |
| 9 | +- `npm i` |
| 10 | +- `npx hardat compile` |
| 11 | +- `npx hardhat test` |
| 12 | + |
| 13 | +## Overview |
| 14 | +- in order for a decentralized exchange to work like Uniswap, we need a set of users to add/remove funds liquidity pool. They are incentivized with fees from trades (aka `swaps`). |
| 15 | +- when Liquidty Providers add liquidity, they get LP tokens to keep track of their contribution. When they want to cash in on fees from transactions and back their funds, they remove liquidty by burning tokens. |
| 16 | +- Once there is any liquidty, people can execute trades using `swap` method |
| 17 | +- The functionality is split into 2 contracts `Router.sol` and `LiquidityPool.sol` as was done in Uniswap. Router is supposed to be the one that interfaces with end users. It ensures that users don't un-necessarily lose money during trades. LiquidityPool is a low level contract that keeps track of the state of luqidity and funds |
| 18 | + |
| 19 | +## Technical Implementation |
| 20 | + |
| 21 | +### Router.sol (Router Contract) |
| 22 | + |
| 23 | +for all of these functions, user needs to approve the router to send over SPC funds via ERC20 `approve` function |
| 24 | + |
| 25 | +- `addLiquidity` - adds liquidity. eth sent is a constant param. while `spcMin`, `spcMax` are used adjust the SPC token that should be send to LP contract to limit losses. I also used `spcMin` & `spcMax` to simplifiy the logic and not have to refund eth back to user as it seemed more messy |
| 26 | + - i transfer spc in the router method and sent eth via the `mint` LP method |
| 27 | +- `removeLiquidity` - uses liquidity token to remove liquidity. and has min spc and eth params to ensure users gets back at a rate that they are comfortable. if refunding eth and spc meet minimum requirements, then I transfer the lp token to LP contract and call the `burn` method |
| 28 | +- `swap` - allows to swap one asset at a time, either SPC or ETH for one another |
| 29 | + - if swapping ETH for SPC, eth is required to be sent it and `_spcMinOut` needs to be defined |
| 30 | + - if meets requirements I transfer ETH to LP via `swap` method |
| 31 | + - if swapping SPC for ETH, `_spcIn` is required to be sent it and `_ethMinOut` needs to be defined |
| 32 | + - if meets requirements I transfer spc before executing LP `swap` method |
| 33 | + - i added a bunch of checks to make sure mins are met (refer to comments in code) |
| 34 | + |
| 35 | +### LiquidityPool.sol (LP Contract) |
| 36 | + |
| 37 | +- all these are low level calls meant to be sent by router |
| 38 | +- I added warlock to limit re-entrancy attacks and generally enforced users not to send wacky numbers and did my best to prevent from users trying to mess up the liquidity numbers by having a good amount of `require` checks in many places |
| 39 | + |
| 40 | +- `mint` |
| 41 | + - on first `mint` event uses geometric mean |
| 42 | + - in subsequent executions, keeps the ratio of SPC to ETH while depositing them and issuing LP tokens to the `_to` address |
| 43 | + - updates the reserve values |
| 44 | +- `burn` |
| 45 | + - checks the balance of LP tokens sent to LP contract. and sends corresponding SPC and SPC to `_to` address |
| 46 | + - burns the LP tokens out of circulation |
| 47 | + - updates the reserve values |
| 48 | +- `swap` |
| 49 | + - takes 1% fee on all trades |
| 50 | + - uses constant product formula |
| 51 | + - checks with `_ethIn` if eth is sent in. if yes, assumes you're swapping ETH for SPC |
| 52 | + - if SPC for ETH, checks LP balance of SPC and compares to reserve |
| 53 | + - after calculations, reserves are updated and spc/eth is sent out to the `_to` address |
| 54 | + |
| 55 | +### Front-end |
| 56 | + |
| 57 | +- make sure to use Goerli test network |
| 58 | +- in order to be able to deposit and withdraw, you need to click on the 2 `appprove spc` and `approve lp` buttons |
| 59 | +- withdraw function was added to the ICO assignment. it is called: `withdrawFunds`. Reference: https://github.com/0xMacro/student.andriy-kulak/blob/ea655f5d911c3b1dc2910b916cc10d841f24d782/ico/contracts/SpaceCoinICO.sol#L247-L259 |
| 60 | + - because I only had like 2.3 ETH on goerli network, I couldn't add much to the pool |
| 61 | +- I didn't have time to implement buying of SPCs directly from ICO into the front-end (but that wasn't really part of the spec anyway) |
| 62 | +- I added images and addresses that I am using for the contracts |
| 63 | + |
| 64 | +#### Commands for Frontend |
| 65 | + |
| 66 | +- `cd frontend-2` |
| 67 | +- `npm install` |
| 68 | +- `npm start` |
| 69 | +- fe should be available on `http://localhost:1234/` |
| 70 | + |
| 71 | +### Test Coverage |
| 72 | + |
| 73 | +- I spent a lot of time covering the important test cases of business |
| 74 | +- There are some less important `require` checks that are not tested like for money and eth transfers. I didn't have time to test those and I wasnt' sure how to fail a transfer or an eth trasaction very easily. and I didn't test all branches on sqrRoot method since I copied it from uniswap |
| 75 | + |
| 76 | + |
| 77 | +#### Deploy Script |
| 78 | + |
| 79 | +- `npx hardhat run --network goerli scripts/deploy.ts --show-stack-traces` |
| 80 | + |
| 81 | +#### Updated Settings I use Personally |
| 82 | +- this repo is configured with hardhat template with prettier, eslint, vscode config, tsconfig. These are mostly pre-defined by hardhat template and make it very easy to start working and deploy contracts |
0 commit comments