{"id":20433903,"url":"https://github.com/flashbots/mev-inspect-py","last_synced_at":"2025-07-13T09:32:36.512Z","repository":{"id":37686178,"uuid":"380056929","full_name":"flashbots/mev-inspect-py","owner":"flashbots","description":"🔎 an MEV inspector for Ethereum 🔎","archived":true,"fork":false,"pushed_at":"2024-11-27T21:42:52.000Z","size":7359,"stargazers_count":843,"open_issues_count":54,"forks_count":266,"subscribers_count":42,"default_branch":"main","last_synced_at":"2025-07-10T15:48:31.258Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flashbots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-24T21:43:04.000Z","updated_at":"2025-06-18T09:04:33.000Z","dependencies_parsed_at":"2024-11-15T08:34:41.742Z","dependency_job_id":null,"html_url":"https://github.com/flashbots/mev-inspect-py","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/flashbots/mev-inspect-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fmev-inspect-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fmev-inspect-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fmev-inspect-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fmev-inspect-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flashbots","download_url":"https://codeload.github.com/flashbots/mev-inspect-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Fmev-inspect-py/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265120213,"owners_count":23714490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T08:22:19.111Z","updated_at":"2025-07-13T09:32:36.506Z","avatar_url":"https://github.com/flashbots.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"⚠️ This tool has been deprecated. You can visit [Flashbots Data](https://datasets.flashbots.net/) for historical mev-inspect data on Ethereum and join us on the [Flashbots forum](https://collective.flashbots.net). ⚠️\n\n# mev-inspect-py\n\n[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)\n[![Discord](https://img.shields.io/discord/755466764501909692)](https://discord.gg/7hvTycdNcK)\n\n[Maximal extractable value](https://ethereum.org/en/developers/docs/mev/) inspector for Ethereum, to illuminate the [dark forest](https://www.paradigm.xyz/2020/08/ethereum-is-a-dark-forest/) 🌲💡\n\nGiven a block, mev-inspect finds:\n- miner payments (gas + coinbase)\n- tokens transfers and profit\n- swaps and [arbitrages](https://twitter.com/bertcmiller/status/1427632028263059462)\n- ...and more\n\nData is stored in Postgres for analysis.\n\n## Install\n\nmev-inspect-py is built to run on kubernetes locally and in production.\n\n### Dependencies\n\n- [docker](https://www.docker.com/products/docker-desktop)\n- [kind](https://kind.sigs.k8s.io/docs/user/quick-start), or a similar tool for running local Kubernetes clusters\n- [kubectl](https://kubernetes.io/docs/tasks/tools/)\n- [helm](https://helm.sh/docs/intro/install/)\n- [tilt](https://docs.tilt.dev/install.html)\n\n### Set up\n\nCreate a new cluster with:\n\n```\nkind create cluster\n```\n\nSet an environment variable `RPC_URL` to an RPC for fetching blocks.\n\nmev-inspect-py currently requires a node with support for Erigon traces and receipts (not geth yet 😔).\n\n[pokt.network](https://www.pokt.network/)'s \"Ethereum Mainnet Archival with trace calls\" is a good hosted option.\n\nExample:\n\n```\nexport RPC_URL=\"http://111.111.111.111:8546\"\n```\n\n\nNext, start all services with:\n\n```\ntilt up\n```\n\nPress \"space\" to see a browser of the services starting up.\n\nOn first startup, you'll need to apply database migrations with:\n\n```\n./mev exec alembic upgrade head\n```\n\nAnd load prices data\n\n```\n./mev prices fetch-all\n```\n\n## Monolithic (non-kubernetes) install instructions\n\nFor an alternative means of running mev-inspect-py for smaller set-ups or debug purposes see the [monolithic install instructions](MONOLITHIC.md).\n\n## Usage\n\n### Inspect a single block\n\nInspecting block [12914944](https://twitter.com/mevalphaleak/status/1420416437575901185):\n\n```\n./mev inspect 12914944\n```\n\n### Inspect many blocks\n\nInspecting blocks 12914944 to 12914954:\n\n```\n./mev inspect-many 12914944 12914954\n```\n\n### Inspect all incoming blocks\n\nStart a block listener with:\n\n```\n./mev listener start\n```\n\nBy default, it will pick up wherever you left off.\nIf running for the first time, listener starts at the latest block.\n\nTail logs for the listener with:\n\n```\n./mev listener tail\n```\n\nAnd stop the listener with:\n\n```\n./mev listener stop\n```\n\n### Backfilling\n\nFor larger backfills, you can inspect many blocks in parallel\n\nTo inspect blocks 12914944 to 12915044, run\n```\n./mev backfill 12914944 12915044\n```\n\nThis queues the blocks in Redis to be pulled off by the mev-inspect-worker service\n\nTo increase or decrease parallelism, update the replicaCount value for the mev-inspect-workers helm chart\n\nLocally, this can be done by editing Tiltfile and changing \"replicaCount=1\" to your desired parallelism:\n```\nk8s_yaml(helm(\n    './k8s/mev-inspect-workers',\n    name='mev-inspect-workers',\n    set=[\"replicaCount=1\"],\n))\n```\n\nYou can see worker pods spin up then complete by watching the status of all pods\n```\nwatch kubectl get pods\n```\n\nTo see progress and failed batches, connect to Redis with\n```\n./mev redis\n```\n\nFor total messages, query:\n```\nHLEN dramatiq:default.msgs\n```\n\nFor messages failed and waiting to retry in the delay queue (DQ), query:\n```\nHGETALL dramatiq:default.DQ.msgs\n```\n\nFor messages permanently failed in the dead letter queue (XQ), query:\n```\nHGETALL dramatiq:default.XQ.msgs\n```\n\nTo clear the queue, delete keys for the main queue and delay queue\n```\nDEL dramatiq:default.msgs\nDEL dramatiq:default.DQ.msgs\n```\n\nFor more information on queues, see the [spec shared by dramatiq](https://github.com/Bogdanp/dramatiq/blob/24cbc0dc551797783f41b08ea461e1b5d23a4058/dramatiq/brokers/redis/dispatch.lua#L24-L43)\n\n**Backfilling a list of blocks**\n\nCreate a file containing a block per row, for example blocks.txt containing:\n```\n12500000\n12500001\n12500002\n```\n\nThen queue the blocks with\n```\ncat blocks.txt | ./mev block-list\n```\n\nTo watch the logs for a given worker pod, take its pod name using the above, then run:\n```\nkubectl logs -f pod/mev-inspect-worker-abcdefg\n```\n\n(where `mev-inspect-worker-abcdefg` is your actual pod name)\n\n\n### Exploring\n\nAll inspect output data is stored in Postgres.\n\nTo connect to the local Postgres database for querying, launch a client container with:\n\n```\n./mev db\n```\n\nWhen you see the prompt:\n\n```\nmev_inspect=#\n```\n\nYou're ready to query!\n\nTry finding the total number of swaps decoded with UniswapV3Pool:\n\n```\nSELECT COUNT(*) FROM swaps WHERE abi_name='UniswapV3Pool';\n```\n\nor top 10 arbs by gross profit that took profit in WETH:\n\n```\nSELECT *\nFROM arbitrages\nWHERE profit_token_address = '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'\nORDER BY profit_amount DESC\nLIMIT 10;\n```\n\nPostgres tip: Enter `\\x` to enter \"Explanded display\" mode which looks nicer for results with many columns.\n\n## FAQ\n\n### How do I delete / reset my local postgres data?\n\nStop the system if running:\n\n```\ntilt down\n```\n\nDelete it with:\n\n```\nkubectl delete pvc data-postgresql-postgresql-0\n```\n\nStart back up again:\n\n```\ntilt up\n```\n\nAnd rerun migrations to create the tables again:\n\n```\n./mev exec alembic upgrade head\n```\n\n### I was using the docker-compose setup and want to switch to kube, now what?\n\nRe-add the old `docker-compose.yml` file to your mev-inspect-py directory.\n\nA copy can be found [here](https://github.com/flashbots/mev-inspect-py/blob/ef60c097719629a7d2dc56c6e6c9a100fb706f76/docker-compose.yml)\n\nTear down docker-compose resources:\n\n```\ndocker compose down\n```\n\nThen go through the steps in the current README for kube setup.\n\n### Error from server (AlreadyExists): pods \"postgres-client\" already exists\n\nThis means the postgres client container didn't shut down correctly.\n\nDelete this one with:\n\n```\nkubectl delete pod/postgres-client\n```\n\nThen start it back up again.\n\n## Maintainers\n\n- [@lukevs](https://github.com/lukevs)\n- [@gheise](https://github.com/gheise)\n- [@bertmiller](https://github.com/bertmiller)\n\n## Contributing\n\n[Flashbots](https://flashbots.net) is a research and development collective working on mitigating the negative externalities of decentralized economies. We contribute with the larger free software community to illuminate the dark forest.\n\nYou are welcome here \u003c3.\n\n- If you want to join us, come and say hi in our [Discord chat](https://discord.gg/7hvTycdNcK).\n- If you have a question, feedback or a bug report for this project, please [open a new Issue](https://github.com/flashbots/mev-inspect-py/issues).\n- If you would like to contribute with code, check the [CONTRIBUTING file](CONTRIBUTING.md).\n- We just ask you to be nice.\n\n## Security\n\nIf you find a security vulnerability on this project or any other initiative related to Flashbots, please let us know sending an email to security@flashbots.net.\n\n---\n\nMade with ☀️  by the ⚡🤖 collective.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflashbots%2Fmev-inspect-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflashbots%2Fmev-inspect-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflashbots%2Fmev-inspect-py/lists"}