Merge pull request #8 from skip-mev/v2

Merge v2 into main

.gitignore

@@ -1,3 +1,9 @@
 /venv/
 /__pycache__/
-juno-arb/__pycache__/
+/cyclic-arbitrage/__pycache__/
+.DS_Store
+/tests/__pycache__/
+.vscode
+.pytest_cache
+*.pyc
+/junk/

CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Alpha Left For Searchers
+- n-pool cyclic arbitrage routes, n != 3
+- parsing / backrunning dex aggregator txs
+- parallelizing bot for faster optimal route choosing
+- searching non x*y=k pools
+- searching long-tail opportunities
+- searching cross-chain opportunities
+- searching cex/dex opportunities
+- Juno:
+    - Support for WYND DEX (juno_contracts.json includes JunoSwap pools pre-migration)
+
+## Work-In-Progress
+- EVM/CW Contract Execution (Multi-messages cannot be used for EVM chains)
+- EVMOS Support
+- Testing Suite
+- Batch Tendermint RPC Queries
+- Mempool Parsing for DEX Router Txs
+
+## v2 - 2023-01-12
+- General
+    - Refactored codebase for easier extendability to more chains, protocols, and searching strategies
+    - Added support for Terra 2
+    - Added support for bids as a percentage of profit (configurable in .env files)
+    - Added support to derive pools and routes from factory contracts (hardcoding still necessary for non-factory dexes)
+    - Moved all config variables from main.py to .env files in envs/
+    - Added a switch in main.py to choose network
+- Networks:
+    - Terra 2:
+        - Added support for Astroport, Phoenix, TerraSwap, and WhiteWhale pools
+        - Currently must be run on a local node to avoid rate limiting on public Terra 2 nodes
+    - Juno:
+        - Added support for parsing Loop and White Whale pool swaps from the mempool
+- Cyclic Arbitrage
+    - Added support for different fees across pools
+    - Added support for pool fees coming out of input and/or output denoms
+
+## v1 - 2022-11-15
+- Skipper is born!
+- Networks:
+    - Juno:
+        - Added support for arbing across JunoSwap and Loop pools
+        - Added support for parsing JunoSwap swaps from mempool
+- MEV Opportunities Supported:
+    - 3-Pool Cyclic Arbitrage (single fee across all pools)
+        - Optimal Amount In Algo: https://arxiv.org/abs/2105.02784

Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.10
+
+RUN apt-get update && apt-get install -y nano
+
+# Set the working directory to /app
+WORKDIR /
+
+# Copy the current directory contents into the container at /app
+COPY . /
+
+# Install any needed packages specified in requirements.txt
+RUN pip install -r requirements.txt
+
+# Run the app when the container launches
+CMD ["python", "-u", "main.py"]

README.md

@@ -1,6 +1,6 @@
-# Skip Searchers
+# Skipper
 
-Example MEV searching bots for the Cosmos ecosystem, using Skip.
+Example MEV searching bot for the Cosmos ecosystem, using Skip.
 
 ``` python
 """
@@ -24,11 +24,8 @@ Example MEV searching bots for the Cosmos ecosystem, using Skip.
 
 # Overview
 
-This repository contains example MEV bots that search for and executes on
-profitable MEV opportunities throughout the Interchain, starting with Juno.
-
-Each subdirectory corresponds to a different bot. The README in each subdirectory 
-contains more information about the bot and a quickstart guide for using it. 
+This repository contains an example MEV bot that searches for and executes on
+profitable MEV opportunities throughout the Interchain, starting with Juno and Terra 2.
 
 * If you're new to MEV or searching, use this repo as an educational tool to 
 help you learn the what and how of searching. 
@@ -42,8 +39,160 @@ For an overview of Skip, please see: https://woolen-background-b64.notion.site/S
 
 # About our bots
 
-* `juno-arb`: A Python bot for JUNO that captures cyclic arbitrage opportunities across
-JUNO's two major DEXes--JunoSwap and Loop DEX--by backrunning transactions 
-that trade against particular pools. You can read more about JUNO, Loop DEX, and JunoSwap 
-in our [state of JUNO MEV report](https://medium.com/@skip_protocol/skips-state-of-mev-juno-667a51a17b70)
+Skipper is a Python-based bot for Cosmos that captures cyclic arbitrage opportunities across all major DEXs on Juno and Terra 2 by backrunning transactions that trade against particular pools. You can read more about JUNO, Loop DEX, and JunoSwap in our [state of JUNO MEV report](https://medium.com/@skip_protocol/skips-state-of-mev-juno-667a51a17b70)
+
+
+# Quick Start
+
+This bot requires:
+
+- Python 3.10
+
+### **Install Python 3.10** ###
+```
+sudo apt update && sudo apt upgrade -y
+sudo apt-get install software-properties-common
+sudo add-apt-repository ppa:deadsnakes/ppa
+sudo apt install python3.10 python3-pip python3-virtualenv python3.10-distutils 
+```
+
+Check your Python 3.10 is functioning:
+
+```
+python3.10 --version
+```
+
+Clone the repository:
+```
+git clone https://github.com/skip-mev/skipper.git
+```
+
+Move into the directory:
+```
+cd skipper
+```
+
+Create a virtual environment
+```
+python3.10 -m virtualenv venv
+```
+
+Activate virtual Environment, (venv) will show on left-hand side of shell
+```
+source venv/bin/activate
+```
+
+Once you have python 3.10 and are in the directory, install all the dependencies:
+```
+pip install -r requirements.txt
+```
+
+Edit files in envs/ to your liking (specifiying your mnemonic, profit as bid %, choosing node to query from).
+
+The most important being your mnemonic, creating a new wallet is highly suggested for security, and for this wallet to only be used for this bot, as your mnemonic must be entered. 
+```
+MNEMONIC = "<your mnemonic>"
+```
+
+Choose the specific .env file you want to target in `main.py` (change based on network run)
+```
+# Load environment variables
+load_dotenv('envs/juno.env')
+#load_dotenv('envs/terra.env')
+```
+
+Lastly, run the bot:
+```python
+python3.10 main.py
+```
+To leave the virtual environment use command
+```
+deactivate
+```
+
+# Run bot with docker
+
+### **Install pre-requisites** ###
+```
+sudo apt update -y && apt upgrade -y && apt autoremove -y
+sudo apt install docker.io docker-compose -y
+```
+
+Edit files in envs/ to your liking (specifiying your mnemonic, profit as bid %, choosing node to query from).
+
+The most important being your mnemonic, creating a new wallet is highly suggested for security, and for this wallet to only be used for this bot, as your mnemonic must be entered. 
+```
+MNEMONIC = "<your mnemonic>"
+```
+
+Choose the specific .env file you want to target in `main.py` (change based on network run)
+```
+# Load environment variables
+load_dotenv('envs/juno.env')
+#load_dotenv('envs/terra.env')
+```
+
+Build the docker image
+``` 
+docker build -t mevbot .
+```
+
+Run the docker image
+```
+docker run -d --name mevbot mevbot:latest
+```
+
+Shell into container & check logs (if running on terra, log will be logs/terra.log)
+```
+docker exec -it mevbot cat logs/juno.log
+```
+
+Change env variables after image is built
+```
+docker exec -it mevbot /bin/sh
+```
+```
+cd envs && nano juno.env -> edit to your liking
+```
+```
+exit
+```
+```
+docker restart mevbot
+```
+
+# How the Bot Works
+
+This example bot searches for 3-pool cyclic arbitrage opportunities
+on Juno mainnet. A cylic arb route is a collection of pools and corresponding
+swaps that result in receiving more of the same asset than was put in. 
+
+An example is as follows:
+```bash
+Swaps:
+Pool 1: A -> B
+Pool 2: B -> C
+Pool 3: C -> A
+
+Transfers: 100 Token A -> 20 Token B -> 150 Token C -> 120 Token A
+```
+
+In particular, this bot reads from a contracts.json file that has contract addresses
+of popular pools on JunoSwap and Loop Dex. In addition, for each pool, the file also 
+has a list of 3-pool cyclic routes. Using this file, the high level steps are:
+
+1. Continously query rpc node for current mempool txs (unconfirmed Txs)
+2. Parse txs in mempool and look for swaps against JunoSwap pools
+3. When a swap is found, grab the current reserve amounts for the pools we're tracking
+4. Simulate the swap tx and update the reserves for the pools swapped against
+5. Check if the swap created a cylic arb in any of our routes of interest
+7. If an arb opportunity is created, find the optimal amount to put into the route
+8. Check how profitable the cyclic arb would be after gas and bidding costs
+9. If it's profitable after costs, then send a bundle to the Skip Auction
+
+# We're Here To Help
+
+If you have any questions, join our discord and ask in the
+traders channel! Got our Skipper interns monitoring 24/7.
 
+Discord: https://discord.gg/UgazvFgKef