https://github.com/cowprotocol/ebbo

https://github.com/cowprotocol/ebbo

Last synced: about 1 year ago
JSON representation

• Host: GitHub
• URL: https://github.com/cowprotocol/ebbo
• Owner: cowprotocol
• License: mit
• Created: 2023-02-27T19:50:02.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2025-03-05T17:26:13.000Z (about 1 year ago)
• Last Synced: 2025-04-12T23:13:46.060Z (about 1 year ago)
• Language: Python
• Size: 323 KB
• Stars: 6
• Watchers: 3
• Forks: 1
• Open Issues: 20
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          

# Ethereum Best Bid/Offer (EBBO) Monitoring Tool

  

This tool monitors all settlements that happen on-chain, focusing on EBBO testing. More concretely, we promise our users that they will get a price that is at least as good as what they can find on other DEXs. By parsing publicly available liquidity, we can monitor how often solver solutions with better surplus could have been provided.

  

## Scripts

The project consists of 3 main components: 


1. In the first component, for each auction, we look at all solutions that did NOT win and check whether any of them actually provided a better deal to an order that got executed by the winning solution. This currently is best used for analyzing historical data. This script utilizes the callData of all solutions.

The output consists of all orders that could have provided the user a better surplus with corresponding solver and absolute/relative values of the surplus difference. It also provides the error rate of each solver. The competition endpoint is used for this. To run this, set start_block, end_block or tx_hash in `test.py`.




2. The second component is a spin-off from the first that serves as a live logging tool which gathers the most recent settlements on CoW Protocol, and checks them for EBBO. 





3. The third component relies on on-chain data and the instance.json describing the auction. This component parses all settlements that happened on-chain, recovers the surplus that each order got, and for each executed order, calls Quasimodo and requests a solution that only executes that order. Then, it checks what surplus Quasimodo gives to that order and compares with what happened on-chain.

  

## Setup Project

Clone Repository: 


  

    git clone https://github.com/cowprotocol/ebbo.git

Version python 3.12 is used. 


### Dependencies:

Install the following libraries as dependencies. 


    pip install requests

    

    pip install web3

    

    pip install dune-client

    

    pip  install  python-dotenv

  

To test either of the components, create a `.env` file in the root directory (ebbo) and set variables `ETHERSCAN_KEY` and `INFURA_KEY` as string values from [Etherscan API Key](https://etherscan.io/myapikey) in your profile and Infura once you have an account created one. You can also set `NODE_URL` instead of `INFURA_KEY` if you are using a different RPC provider. You will also need a `DUNE_KEY` for running the historical data test. 


Sample `.env` structure:

    INFURA_KEY = 'string key here'

    ETHERSCAN_KEY = 'string key here'

    DUNE_KEY = 'string key here'

*To start the EBBO daemon, run the following from the ebbo directory:* 


    python3 -m src.daemon

*If you wish to run the EBBO tool over historical data, set the (start_block, end_block) or tx_hash in `test.py` and run the following from the ebbo directory:* 


       python3 -m tests.e2e.test

You should be good to go now!