reorg-monitor

README

Ethereum Reorg Monitor

Watch and document Ethereum reorgs, including miner values of blocks.

• Subscribe to multiple Ethereum nodes for new blocks (via WebSocket or IPC connection)
• Capture block value (gas fees and smart contract payments) by simulating blocks with mev-geth
• Collect data in a Postgres database (summary and individual block info)
• Webserver that shows status information and recent reorgs

This project is work in progress and there may be bugs, although it works pretty stable now. Please open issues if you have ideas, questions or want to contribute :)

---

• Ethereum Reorg Monitor
  • Getting started
  • Codebase Overview & Architecture
  • Notes & References
  • Maintainers
  • Security

Getting started

• Clone this repository
• For database testing, you can use docker-compose up to start a local Postgres database and adminer
• See .env.example for environment variables you can use (eg create .env.local and use them with source .env.local).
• Start the monitor:

# Normal run, print only
$ go run cmd/reorg-monitor/main.go --ethereum-jsonrpc-uris ws://geth_node:8546

# Simulate blocks in a reorg - note: this requires passing in one or more RPC endpoints that support eth_callBundle API
# The Flashbots RPC endpoints can be used to simulate blocks, for additional details see: https://docs.flashbots.net/flashbots-auction/searchers/advanced/rpc-endpoint#bundle-relay-urls
$ go run cmd/reorg-monitor/main.go --simulate-blocks --mev-geth-uri https://relay.flashbots.net --ethereum-jsonrpc-uris ws://geth_node:8546

# Save to database
$ go run cmd/reorg-monitor/main.go --simulate-blocks --mev-geth-uri https://relay.flashbots.net --postgres-dsn ${POSTGRES_DSN_HERE} --ethereum-jsonrpc-uris ws://geth_node:8546

# Get status from webserver
$ curl localhost:9094

You can also install the reorg monitor with go install:

$ go install github.com/flashbots/reorg-monitor/cmd/reorg-monitor@latest
$ reorg-monitor -h

---

Codebase Overview & Architecture

See also: Story of an Ethereum Reorg

Code layout:

• cmd/reorg-monitor is the main command-line entrypoint
• cmd/reorg-monitor-test is used for local testing and development
• monitor module - block collection: subscription to geth nodes, building a history of as many blocks as possible
• analysis module - detect reorgs by building a tree data structure of all known blocks (blocks with >1 child start a reorg)

---

Notes & References

• https://beaconscan.com/slots-forked
• etherscan.io/blocks_forked
• etherscan.io/chart/uncles
• Story of an Ethereum Reorg
• go-ethereum WriteBlock function, which calls the reorg method if a block is seen of which the parent is not the current block
• Ethereum Whitepaper: Modified GHOST Implementation
• Ethereum Yellow Paper
• Ghost whitepaper
• For Ethereum 2.0: Combining Ghost and Casper

See also:

• An Empirical Analysis of Chain Reorganizations and Double-Spend Attacks on Proof-of-Work Cryptocurrencies (pdf)

Tools:

• https://composer.alchemyapi.io - to find out more about non-mainchain blocks (eth_getBlockByHash)
• https://mermaid-js.github.io/mermaid-live-editor

Maintainers

This project is currently maintained by:

• @metachris
• @wazzymandias

Security

If 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.