Flashbots Recovery Py

A Python script that uses Flashbots to create Ethereum transaction bundles. Based off of Flashbots' Python library example.

Requirements

1. Git - Install Git
   1. Check if you have Git installed with git --version
2. Python (>=3.10; <4) - Install Python (Windows), Install Python (Linux)
   1. Check if you have Python installed with python3 --version
3. Pip - Install Pip
   1. Check if you have Pip installed with pip --version
4. Poetry - Install Poetry (preferrably with pipx)
   1. Check if you have Poetry installed with poetry --version

Usage (Linux)

Installing

Clone this repo

git clone https://github.com/vile/flashbots-recovery-py.git
cd flashbots-recovery-py

Install dependencies using Poetry

make deps

Rename .env.example

mv .env.example .env

Include your Alchemy API key, compromised & gasser private keys, and recovery wallet address.

Running the script

make start

Usage (Windows)

Installing

Clone this repo (Git)

git clone https://github.com/vile/flashbots-recovery-py.git
cd flashbots-recovery-py

Clone this repo (HTTPS)

1. At the top right of the repo on GitHub, click the green Code button, then under HTTPS click Download ZIP.
2. Extract the downloaded archive to a folder like your Desktop using any ZIP tool (such as WinRAR, 7Zip, or NanaZip).
3. Navigate to the extracted folder.

Download repo via HTTPS

Install dependencies using Poetry

poetry install --no-root

Rename .env.example

Remove the .example file extension from the .env.example file. Include your Alchemy API key, compromised & gasser private keys, and recovery wallet address.

Running the script

poetry run py main.py

Creating a Bundle

In most cases, two seperate wallets are required to complete a rescue: a wallet that provides ETH for gas fees (the "gasser" wallet), and the wallet in which assets are being recovered from (the "compromised" wallet). Providing ETH from a secondary wallet in the same bundle elimates issues with sweeper bots.

A transaction bundle is atomic, meaning the bundle will only be mined if all the transactions within the bundle will execute successfully in the same block.

Providing gas

A simple and generic ETH transfer transaction already exists in bundle.py. Most of the time, you will only need to change the value (amount) of ETH sent (default: 0.01 ETH). However, if there is a case where the gasser wallet needs to execute multiple transaction before the compromised wallet, it is extensible.

Rescueing assets

Transactions in compromised_wallet_txs completely depend on what interactions are required to rescue assets. Generic (partial) ABIs are provided for all major ERCs (ERC721, ERC1155, and ERC20), along with a generic batch transfer contract. In the case where transactions interact with non-ERC-conforming tokens or custom contracts, you can either put your own ABI in utils.abi, or manually construct the calldata and include it in the data field of the tx.

Incrementing nonce

As each entry in compromised_wallet_txs is executed seperately, every new transaction needs to have a properly incremented nonce attached to it.

Incrementing Nonce Between Transactions

   # transaction 1
   {
      ...
      "nonce": w3.eth.get_transaction_count(
            constants.ETH_COMPROMISED_ACCOUNT_SIGNER.address
        ),
      ...
   },
   # transaction 2
   {
      ...
      "nonce": w3.eth.get_transaction_count(
            constants.ETH_COMPROMISED_ACCOUNT_SIGNER.address
        ) + 1,
      ...
   }

Examples

Examples are viewable under the examples folder.