https://github.com/api3dao/oev-v1-compound-bot
A searching bot for Compound protocol using OEV v1 proxies
https://github.com/api3dao/oev-v1-compound-bot
Last synced: 4 months ago
JSON representation
A searching bot for Compound protocol using OEV v1 proxies
- Host: GitHub
- URL: https://github.com/api3dao/oev-v1-compound-bot
- Owner: api3dao
- License: mit
- Created: 2024-09-23T08:33:37.000Z (over 1 year ago)
- Default Branch: oev
- Last Pushed: 2025-03-11T17:48:04.000Z (about 1 year ago)
- Last Synced: 2025-06-23T14:47:41.015Z (11 months ago)
- Language: Solidity
- Size: 182 KB
- Stars: 5
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OEV v1 Compound Example Bot
> An example Compound3 bot showcasing Api3 OEV solution
⚠️ This bot was designed for a specific Compound3 deployment that we maintained with a dedicated market and UI at https://github.com/api3dao/oev-v1-compound. That repository has since been archived and testing infrastructure is no longer available. While the bot cannot be directly tested anymore, the codebase serves as a valuable reference for searchers implementing similar functionality. ⚠️
This repository documents the necessary steps to update an MEV bot to an OEV bot. While the main branch is the final
result of the OEV bot, there are branches for the previous steps, so one can easily compare the changes.
## MEV bot
On branch [mev](https://github.com/api3dao/oev-v1-compound-bot/tree/mev)
First step is to have an MEV bot that can perform liquidations when the opportunity to do so arises. For more
information, refer to [From MEV Searching](https://docs.api3.org/oev-searchers/in-depth/#from-mev-searching).
## MEV with Signed APIs bot
Changes [mev -> mev-with-signed-apis](https://github.com/api3dao/oev-v1-compound-bot/compare/mev...mev-with-signed-apis)
Second step is to extend the MEV bot to utilize the public Base Feed Endpoints. The existing MEV bot can utilize this
off-chain open source data and make a base feed update on-chain whenever there is OEV to be captured. For more
information, refer to [MEV with Signed APIs](https://docs.api3.org/oev-searchers/in-depth/mev-with-signed-apis.html).
## OEV bot
Changes [mev-with-signed-apis -> oev](https://github.com/api3dao/oev-v1-compound-bot/compare/mev-with-signed-apis...oev)
Final step is to transition to utilizing the OEV network to acquire the exclusive privilege to update the data feeds.
For more information, refer to [OEV Searching](https://docs.api3.org/oev-searchers/in-depth/oev-searching.html).
## How to
### Preparation
Install node modules.
```bash
pnpm install
pnpm run build
```
### CLI Utils
The bot has a set of CLI commands, executable by
```bash
pnpm run bot:cli-utils
```
where \ can be one of the following:
- `deploy` - This deploys the Liquidator contract, resulting address of which has to be configured in the `.env` file
- `prepare-positions-to-watch` - Prepares positions to watch, continuing from the last block number saved in the
`all-positions.json` file. More details below in the Bot Concepts section.
- `reset-positions-to-watch` - Similar to `prepare-positions-to-watch`, but it starts from block zero.
### Configuration
All bots require configuration.
Refer to `.env.example` for the .env configuration. Ensure this file has been copied to `.env` and has been configured.
The example ENV file contains recommended ENV variables for the each bot.
### Running the bot
Bot can be run directly with `ts-node` by
```bash
pnpm run bot:run
```
## Bot concepts
There are 2 main folders:
- `contracts` - Smart contracts of necessary Compound V3 and Uniswap V3 interfaces, Multicall3 for batching multiple
smart contract calls in one transaction, and our Compound3Liquidator.
- `src` - Source code of the bot and stored data.
### Storage
The bot has an in-memory storage, which is defined in the `src/lib/storage.ts`. The storage is initialized when the bot
is started, and keep all the important data for the bot execution. Created are also the corresponding connectors for
contracts the bot will be interacting with.
### Positions tracking
A position in the Compound protocol is simply an address of the borrower - this is the identifier when we want to do a
liquidation call. The position tracking functions are located in `src/lib/positions.ts`.
The storage variables `allPositions`, `currentPositions`, and `interestingPositions` are used to track different states
of borrowing positions in the Compound protocol. `allPositions` tracks all positions that have ever executed a borrow
action. `currentPositions` is a subset of `allPositions` and includes only those positions with an active borrowing
status. `interestingPositions` is a further subset of `currentPositions`, representing positions that have crossed a
specific Loan to Value (LTV) threshold.
Since fetching all positions from the beginning of the protocol might take a considerable amount of time, there is an
`all-positions.json` file that is loaded during the bot’s initialization phase and serves as a checkpoint, so the bot
does not need to fetch the entire history each time it restarts. This file can be created and updated by running the CLI
command `prepare-positions-to-watch` mentioned above.
### Liquidation
Liquidations are carried out by interacting with the Compound3Liquidator contract, with specific details depending on
the bot’s current stage. The liquidation logic is slightly different for the OEV bot, as the searcher must first deposit
collateral on the OevAuctionHouse contract before placing a bid to qualify for receiving update details and then must
also pay for the awarded bid. Both actions are conducted on the OEV Network. The liquidation functions are located in
`src/lib/oev-liquidation.ts`.
The process in general is as follows:
1. A list of possible liquidatable positions is filtered from the `interestingPositions` by simulating the liquidations
on-chain.
2. A liquidation call with the actual liquidatable positions gets constructed.
3. The call is simulated to get the estimated gas limit.
4. The call is submitted to the network.
5. The result is awaited and logged.
### Bot execution
The bot (`src/oev-liquidation.ts`) runs several asynchronous independent loops at different intervals (defined by `.env`
variables) which perform certain tasks. These are:
- `fetch-and-filter-new-positions` - Fetches logs from the last processed block til the current block of the network in
use. Filters the logs for the `borrow` action and updates `allPositions`. Filters that result based on active borrow
position and updates `currentPositions`. Filters that result based on LTV values and updates `interestingPositions`.
- `reset-current-positions` - Reevaluates the `currentPositions` from `allPositions` and updates them. Also reevaluates
the `interestingPositions` from the updated `currentPositions` and updates them.
- `reset-interesting-positions` - Reevaluates the `interestingPositions` from the updated `currentPositions` and updates
them.
- `initiate-oev-liquidations` - Uses `interestingPositions` to find out any positions that might be able to be
liquidated. If there are any, it executes the liquidation.