Start Here

Introduction and Index

Jul 23, 2022

I’ve written a lot of content and I’m starting to see similar questions in the comments and direct messages.

This index will be locked to the top of the front page, and will serve as your guidepost to the content here. I will edit it after publishing new articles, so check in occasionally to make sure you haven’t missed something.

Where Should I Start?

The most logical way to work through the lessons here is by starting at the very first post and working through each one after, in order.

I wrote the lessons assuming that you have zero knowledge at the beginning, other than some basic technical knowledge. Each successive lesson assumes that you have read the ones before it. I will often spend a lot of time explaining some idea or technique when I introduce it, but afterwards will provide a link back to it or mention it briefly.

How Should I Use the Code?

I encourage you to use the projects that I publish as a general guide. Each will provide code for a working bot that uses the techniques I have previously covered.

The downside of publishing an easily copied bot to a large technical audience is that the specific strategy will become very crowded.

As an example, after I published the sSPELL-SPELL bot, the particular liquidity pool quickly became very active with very familiar looking bots. If you rely solely on my project bots, you will have a bad time as you compete with hundreds of other readers.

Instead of attempting to squeeze profit from the project bot, I want you to explore its structure, understand the strategy, and think about other ways you could use it with other tokens, pools, and blockchains.

Lesson Index

Topics are divided into sections based on a theme. Each bullet point includes a title and a brief summary of what the lesson covers.

Development Environment and Package Setup

Your Development Environment: Setting up Linux, Python, Brownie, and other Python tools
Introduction to Brownie: Connecting Brownie to a blockchain network, generating an account address and private key, accessing the Brownie console to interact with the network.
NOTE: The original lessons were written using Brownie, which is not actively maintained. I identified Ape Framework as a suitable replacement in late 2023, and wrote lessons using it after making the switch.
Loading a Token Smart Contract: Fetching a smart contract from a block explorer, loading it into Brownie, and exploring the built-in methods that Brownie provides to interact with the contract on the console.
Setting Up a Dedicated Bot VPS: Setting up a Linux VPS in the cloud to improve uptime and latency.

Ape Framework

The Great Brownie Replacement: Discussion about Brownie’s transition into maintenance mode, under-the-hood changes to degenbot to eliminate the dependency on Brownie, and discussion of Ape Framework as an alternative.
Introduction to Ape Framework: Setting up Ape, comparison to Brownie, and examples of how to generate and import accounts, connect to a network, send transactions, create a fork, create a contract, and debug/test.
Testing with Ape Framework: Writing pytest-based smart contract tests using Ape. Discussion of testing fixtures, helper managers, scripting, and plugin configuration for Ape projects.

Blockchain Basics

The Blockchain Basics series re-introduces some information with a focus on Ape Framework.

Accounts & Keys: What a private key is, how it is generated from a seed phrase, and how it relates to a public address.
Smart Contracts: What a smart contract is, how is it written, its capabilities and limitations, how they are executed, where their code is stored, how to read them, and how to interact with them.
Forking: How to create a fork of a live blockchain for testing, simulation, and production purposes. Introduces Anvil tool, part of the Foundry toolkit, and Ape’s ape-foundry plugin.

Interacting with the Blockchain Using the Console

Router Contracts — Exploring getAmountsOut(): Loading a UniswapV2-style router contract, sending queries to determine swap rates for arbitrary tokens.
Project: (un)Stablecoin Watcher: Build a very simple bot to watch the swap rates between various stablecoin pairs and print a message when the swap is profitable.
Router Contracts — Swaps and Approvals: Set ERC-20 token allowances for future swapping via the router contract.
Your First Console Swap: Trade a small balance of one stablecoin for another on the console via the router contract.
Your First Automated Swap: Build a more complex bot that automates token approval, continuously monitored swap rates between two stablecoins, and attempts to swap at a profit via the router.
Using a 3rd Party RPC: Signing up with a 3rd party RPC instead of the public RPC for better performance.
Working with ABIs and Unverified Contracts: Loading a contract with an ABI when the source is not published on a block explorer.
Local Forking With Ganache: Launch a local fork, which allows you to test your bot against a local blockchain copy without spending real money or broadcasting public transactions.
NOTE: the original lessons were written using Ganache as the forking tool. Ganache was sunset by its authors in late 2023, which prompted me to replace it with Anvil.
Local Bundle Simulation with Anvil: How to use Anvil to simulate one or more transactions against a forked chain. Introduces the AnvilFork utility class, part of the degenbot Python package.

sSPELL-SPELL Arbitrage

NOTE: the sSPELL-SPELL arbitrage opportunity is long gone. The tokens involved are worthless, and swapping activity is very low. You should not expect to make any money with this bot, but it has been preserved as a curiosity.

Automated Market Makers and the Role of the Arbitrageur: A high level discussion of the positive contribution of an abitrageur.
Lessons Learned from a Successful Arbitrage: A history of my first arbitrage bot and its return on investment.
Bot Building — Setup, Main Loop and Swapping Logic: The complete sSPELL-SPELL bot source code.

Uniswap V2

Fun With Pool Reserves: Calculating swaps directly via formulae, instead of querying getAmountsOut
Pool Reserves — Part II: Partial Swaps, Max Profits: Improving the calculation to support partial swaps at a target ratio.
Pool Reserves — Part III: Swap and Quote Function Upgrades: Implementing direct swap calculation instead of getAmountsOut in a working sSPELL-SPELL bot.
Get a Pair: Querying a UniswapV2 factory contract for liquidity pool addresses, instead of looking them up via the web frontend.

Uniswap V3

Pool Contract: Review the foundational core contract of UniswapV3. Investigate liquidity, ticks, square root price and pool state functions.
Router Contract: Review and test the four types of swaps performed by the UniswapV3 router.
TickLens Contract: Calculate and retrieve the initialized status of multiple tick indices for a known UniswapV3 pool by hand and using the TickLens accessory contract.
Quoter Contract: Calculate gas use and amounts for exactInput and exactOutput swaps using the V3 Quoter accessory contract.
Multicall: Learn how to encode and decode multiple transaction inputs to any V3 contract with built-in multicall functionality.
Swap Prediction — Part I: Predict and verify the behavior of a single pool single tick swap.
Swap Prediction — Part II: Predict and verify the behavior of a single pool multi-tick swap.
Swap Prediction — Part III: Predict and verify the behavior of a multi-pool, multi-tick swap.
Project: Mempool Watcher: Watch and decode mempool transactions sent to the V3 Router contracts, including multicall transactions.
LP Helper — Part I: Develop the basic skeleton of a V3-focused liquidity pool helper class for object-oriented programming in Python.
LP Helper — Part II: Extend the helper to support tick and liquidity fetching from the on-chain contract
Cycle Arbitrage Helper — Part I: Develop the basic skeleton of a V3-compatible cycle arbitrage helper class for object-oriented programming in Python.
Cycle Arbitrage Helper — Part II: Extend the helper to support tracking and updating pool states, swap calculation across multiple pools, and swap input generation using the ported swap function from the Solidity contract.
Cycle Arbitrage Helper — Part III: Extend the helper to generate arbitrage payload generation for arbitrage execution via generic address/calldata payloads.
Project: Uniswap V2 & V3 2-Pool Arbitrage Bot: Build an automated bot that searches and submits 2-pool cycle arbitrage transactions between V2 and V3 pools via Flashbots Auction.

Uniswap V4

Introduction: Review of the Uniswap V4 white paper and deployment.
Pool Manager: Review of the PoolManager contracts and discussion of the individual pool architecture, hooks, and accounting.
Direct Swaps: Guided implementation of a smart contract that implements the necessary functions to perform direct pool swapping without an intermediate router.
Universal Router (V4): Guided walkthrough of using the Universal Router to accomplish swaps without a dedicated smart contract.
Pool Data: Use Cryo to extract the relevant Uniswap V4 pool creation and liquidity events.
State View: Use the StateView accessory library to retrieve pool-specific info from the PoolManager.
Pool Helper: Introduction of the UniswapV4Pool helper class, part of the degenbot Python package.
Projects:
- Uniswap V4/V2 Two-Pool Arbitrage Bot
- Uniswap V4/V3 Two-Pool Arbitrage Bot
- Uniswap V4/V4 Multi-Pool Arbitrage Bot
- Uniswap V4/V3 Multi-Pool Arbitrage

General EVM and Blockchain

Fighting and Winning Gas Wars: Legacy vs. EIP-1559 gas
Chainlink Price Feeds, Calculating Trade EV, Automatically Scaling Gas Fees: Getting on-chain token prices, adjusting trades based on expected value.
EV-Based Gas Scaling: Implementing EV scaling in a working sSPELL-SPELL bot.
Event Listeners: Accessing the built-in “logs” feature to read events emitted when certain blockchain actions occur.
Asynchronous Websocket Listeners: Introduction to asyncio, Python’s concurrent code implementation, and how to monitor multiple websockets for passive monitoring of events, pending transactions, and new blocks.
Multicall Requests: Batch multiple read-only requests using Brownie, instead of sending individual calls. Use the multicall feature to retrieve all known liquidity pools on three Avalanche DEXes.
Encoding and Decoding Calldata with eth_abi: Directly encode and decode byte values for inclusion in calldata (and other things) without using a middleman wrapper function.
Avoiding Trap Tokens With eth_call: Learn how to identify fee/tax on transfer tokens, override storage, balance, and code states for eth_call, and execute arbitrary function calls against a live blockchain without deploying the contract.
Save Gas With Packed Calldata: Reduce gas use by close-packing and decoding calldata inputs to your contract instead of using default padded ABI encoding.

Degenbot Code

The Great Object-Oriented Rewrite: Transforming the monolithic bot structure into reusable Python classes, shared via Github.
Project: Limit Order Bot: Using the degenbot classes to implement a generic “limit order” bot that will wait for favorable ratios and execute one-time trades.
JSON Data Exchange: Read and write JSON to load data between running programs and take advantage of more human-readable data structures.

Smart Contract Arbitrage

Smart Contract Arbitrage — Introduction and Overview: A high level overview of how atomic smart contract swaps work.
Smart Contract Arbitrage — Toolkit and A Simple Contract: Introduction to Vyper and using Brownie to deploy and test smart contracts.
Smart Contract Arbitrage — Interfaces: Using interfaces to access other smart contracts from our smart contract.
Smart Contract Arbitrage — The Flash Borrow Callback: Introduction to the callback feature of the UniswapV2 pair contract which enables flash borrowing.
Smart Contract Arbitrage — Two-Pool Flash Swap: A simple implementation of a Vyper contract that performs two-pool atomic flash swap arbitrage.
Smart Contract Arbitrage — Optimizing the Input: Introduction to SciPy, a module that quickly calculates optimal inputs for the non-linear flash borrow / LP swap arbitrage strategy.
Smart Contract Arbitrage — Towards A Smarter Contract: Implementing better security checks, eliminate the use of the router in favor of swapping directly at the LP contract, and reduce gas use.
Smart Contract Arbitrage — Bot: Build an example bot that drives a two-pool arbitrage smart contract.
Smart Contract Arbitrage — Calldata Pass-through, ABI Encode / Decode, Flexible Fallback: Develop a method to pass arbitrary payloads through the UniswapV2 callback feature, which eliminates the need to use storage variables.
Generalized Vyper Smart Contracts: Introduce the concept of generalized EVM bytecode payloads, which can be executed without using an interface or specific logic for a given external smart contract.
Vyper Bundle Executor: Develop a general-purpose Vyper contract for arbitrary execution of EVM calldata.
Project: gOHM-wsOHM
- Part I: Introduce a traditional bot that executes multi-step arbitrage across two or more blocks.
- Part II: Convert that same multi-step arbitrage strategy into an atomic strategy (single transaction) suitable for execution by the general-purpose bundle executor contract.

Low Level EVM

Opcodes and the Stack: Discussion of the Ethereum Virtual Machine (EVM), the stack, and how to operate on the stack directly using opcodes.
Control Logic: How to implement familiar control structures such as if/else, if/elif/else, and while, using the JUMP and JUMPI opcodes.
Memory: Move beyond the stack and interact with memory.
Storage: Explore storage, both durable and transient.
Huff: Introduction to Huff, a language and compiler that simplifies writing low level EVM contracts without losing access to the stack and opcodes.

Mempool Arbitrage

How I Learned to Stop Worrying and Love the Mempool: Watching pending transactions on Fantom before they are confirmed and recorded to the blockchain.
Snowsight — Getting Started: Introduction to Snowsight, a mempool subscription service for Avalanche, which does not provide public access to the mempool.
Using the Snowsight Transaction Propagator: Use the Snowsight transaction propagator to broadcast trades directly to validators (miners) on the Snowsight network.
Project: Snowsight Arbitrage Bot: Build a bot that uses Snowsight to monitor pending transactions and submit trades to the transaction propagator.
Updates to the Snowsight Bot: Modify the bot to support the changes to the Snowsight after the close of their beta program.
Mempool Backrunning: Extend the Snowsight bot to perform mempool transaction backrunning for a simple two-pool arbitrage.
Predicting The Effect of Mempool Transactions: Generalize the future reserve calculation approach to support multiple token swap types.
Mempool Arbitrage Improvements — Multi-pool Prediction: Extend the generalized future reserve calculation to support overriding the reserves for any LP in a general arbitrage path.

Graph Theory

Find Arbitrage Paths Using Graph Theory and NetworkX: Use NetworkX to automatically build arbitrage pathways from available LP information.
Automatic Arbitrage Path Building: Generalize and automate the arbitrage helper generation from the NetworkX pathways, which eliminates the need to manually enter arbitrage paths.

Local Node Infrastructure

Flashbots

Flashbots — Setup and Identity: Introduction to Flashbots, the private mining pool for MEV searchers, and the Flashbots Auction.
Flashbots — Bundle and Simulate: Learn how to construct a Flashbots-compatible bundle of transactions for submission through the Flashbots relay.
Flashbots — Smart Contract Bribe: Implement the miner bribe, a direct ETH payment, to build more competitive bundles.
Flashbots — Project: Two-Pool UniswapV2 Arbitrage Bot: Build an onchain and mempool backrunning arbitrage bot for two-pool UniswapV2 style opportunities. Uses Flashbots relay for execution.