This repository contains a Proof of Concept (POC) implementation of a liquidation bot capable of liquidating any asset on Morpho Blue.
- Overview
- Detailed Explanation
- Bot Configuration
- Tech Stack
- Lessons Learned
- Run Locally
- Testing
- Acknowledgements
- Feedback
- License
Morpho Blue is a trustless and efficient lending protocol that allows for permissionless market creation. It enables the deployment of minimal and isolated lending markets by specifying:
- One collateral asset
- One loan asset
- A Liquidation Loan To Value (LLTV)
- An Interest Rate Model (IRM)
- An oracle
The protocol is designed to be more efficient and flexible than any other decentralized lending platform.
This repository contains a POC implementation of how liquidations could be executed on any given market. The diagram below provides an overview of how the different components within the bot interact.
The bot uses three key components:
- Task Scheduler
- Redis
- Blockchain Node
- GraphQL
- Markets Behaviour
- Market Behaviour
The task scheduler plans future liquidation executions using asyncio.
Redis is used to cache liquidated positions. Although other packages could be used, Redis is suitable for this implementation. The get_cache
and store_cache
functions return results in JSON format.
The blockchain node is essential for executing liquidations on Morpho Blue.
This section includes two classes:
- Markets Behaviour: Sets up different markets defined by users for liquidation.
- Market Behaviour: Handles market-specific tasks including:
- Allocating each position's health factor
- Fetching positions
- Executing liquidations
- Storing liquidated positions
Liquidations are executed using Multicall, saving gas. Each multicall function processes 100 positions per batch to avoid out-of-gas errors.
The liquidator contract does not immediately swap profits from liquidations, as swapping Token A to Token B for the best quote is an off-chain task. The contract allows the owner to withdraw tokens manually.
To view all liquidations, you can query the Redis DB for all markets where the liquidated property is true. You can use Another Redis Desktop Manager.
To configure the bot, refer to the .env.example
file:
GRAPHQL_API_ENDPOINT=<https://blue-api.morpho.org/graphql>
PRIVATE_KEY=""
LIQUIDATOR_ADDRESS=""
REDIS_HOST=""
RPC_URL="<http://localhost:8545>"
MARKETS=""
MORPHO_ADDRESS=""
INTERVAL=10
- GRAPHQL_API_ENDPOINT: Public endpoint for querying market data on Morpho Blue
- PRIVATE_KEY: Key for executing liquidations
- LIQUIDATOR_ADDRESS: Address of the liquidator contract
- REDIS_HOST: Redis URL for storing market data
- RPC_URL: The RPC URL for connecting to the blockchain
- MARKETS: List of markets for liquidation. Separate multiple markets with commas (e.g., "0x...A,0x...B").
- MORPHO_ADDRESS: Address of the Morpho Blue contract on the chosen network
- INTERVAL: Frequency of bot execution attempts (e.g., 10 = every 10 minutes)
Building a Liquidation Bot requires careful planning due to various factors, especially depending on the chain. For example, on Ethereum, one must carefully manage gas costs during liquidations.
-
Setup Redis using Docker:
docker run -d --name my-redis-stack -p 6379:6379 redis/redis-stack-server:latest
-
Clone the project:
git clone https://github.com/Brianspha/morpho-blue-bot cd morpho-blue-bot
-
Install dependencies:
npm install
-
Setup Python environment:
bash setup_env.bash
-
Setup Foundry, fork Mainnet Ethereum (see
fork.bash.example
), and createfork.bash
:bash fork.bash
-
Deploy local market:
npm run deploy:local
-
Create a
.env
file based on.env.example
and copy relevant values fromdeployment.json
:GRAPHQL_API_ENDPOINT="https://blue-api.morpho.org/graphql" PRIVATE_KEY="private key" LIQUIDATOR_ADDRESS="Liquidator" REDIS_HOST="redis host" RPC_URL="http://localhost:8545" MARKETS="CollatToken" MORPHO_ADDRESS="Morpho" INTERVAL=10
-
Run the bot:
npm run start
To test liquidations executed by the Liquidator contract, run:
npm run test
For feedback, please create an issue.