A Comprehensive Documentation Repository for In-Depth Claude Conversations about Flash Loans, MEV, and DeFi Arbitrage
Documentation Index • Implementation Guides • Architecture Diagrams • Contribute
This repository is a curated knowledge base designed to provide Claude (Anthropic's AI assistant) with comprehensive context about flash loans, MEV (Maximal Extractable Value), and DeFi arbitrage strategies. It enables users to have deep, informed discussions with Claude about these complex topics without repeatedly explaining fundamentals.
For Users Interested in Flash Loans & MEV:
- Get instant, context-aware answers from Claude about flash loan mechanics
- Discuss MEV strategies with full technical context loaded
- Analyze implementation approaches with complete code examples
- Explore profitability and risks with up-to-date information
For Claude:
- Access 76 comprehensive markdown files covering all aspects of flash loans and MEV
- Reference real-world implementations from 41 GitHub repositories
- Provide accurate, nuanced responses based on current (2024-2025) information
- Guide users through complex technical decisions with full context
| Category | Files | Description |
|---|---|---|
| Core Protocols | 7 files | Official Aave V3, Flashbots, provider comparisons |
| Tutorial Guides | 21 files | MEV attacks, defenses, optimization, 2024-2025 trends |
| 🆕 Implementation Guides | 5 files | Complete source code for Solidity, TypeScript, Rust, Python |
| GitHub Examples | 41 files | Real implementations including rusty-sando (857⭐), advanced MEV bots |
| Community Discussions | 2 files | Reddit insights, strategic analyses |
| 🆕 Bot Examples | 4 bots | Production-ready TypeScript bots with full source code |
Total: ~25MB of markdown, ~2M+ tokens of comprehensive flash loan and MEV knowledge
Four complete, educational TypeScript bots with full source code:
| Bot | Type | Purpose | Status |
|---|---|---|---|
| Sandwich Bot | MEV Attack | Understand sandwich attacks | ✅ Complete |
| Flashloan Arbitrage | DeFi Strategy | Aave V3 flashloan arbitrage | ✅ Complete |
| Front-Running | MEV Detection | Detect & analyze front-running | ✅ Complete |
| Back-Running | MEV Strategy | Event-driven arbitrage | ✅ Complete |
See bots/README.md for complete bot documentation and architecture diagrams.
-
Open Claude (claude.ai or Claude Code)
-
Reference documentation using
@syntax:@context/INDEX.md Help me understand flash loan arbitrage opportunities -
Load specific topics:
@context/tutorials/understanding-sandwich-attacks.md Explain how sandwich attacks work and how to defend against them -
Get implementation guidance:
@context/tutorials/sandwich-bot-typescript-implementation.md Help me build a sandwich MEV bot for Arbitrum -
Analyze strategies:
@context/discussions/flashloan-vs-mev-analysis.md Should I build a flash loan arbitrage bot or MEV sandwich bot?
| If You Want To... | Start Here |
|---|---|
| Understand basics | context/core/techopedia-flash-loan-explained.md |
| Compare protocols | context/core/flash-loan-providers-comparison.md |
| Learn about MEV attacks | context/tutorials/understanding-sandwich-attacks.md |
| Protect against MEV | context/tutorials/preventing-front-running-attacks.md |
| Build a bot | context/tutorials/low-budget-sandwich-bot-roadmap.md |
| See architecture | context/tutorials/ARCHITECTURE.md |
| Browse everything | context/INDEX.md |
flashmillion/
├── README.md # This file - start here
├── CLAUDE.md # Project instructions for Claude
│
├── context/ # Main documentation library
│ ├── INDEX.md # 📖 Master catalog of all 76 files
│ │
│ ├── core/ # Protocol documentation (7 files)
│ │ ├── aave-flash-loans-documentation.md
│ │ ├── flashbots-documentation.md
│ │ ├── flash-loan-providers-comparison.md
│ │ └── ...
│ │
│ ├── tutorials/ # Guides & tutorials (21 files)
│ │ ├── ARCHITECTURE.md # Visual system diagrams (Mermaid)
│ │ ├── understanding-sandwich-attacks.md (1500+ lines!)
│ │ ├── preventing-front-running-attacks.md (850+ lines!)
│ │ ├── optimizing-gas-fees.md
│ │ ├── programming-languages-for-flash-loans.md
│ │ │
│ │ ├── 🆕 low-budget-sandwich-bot-roadmap.md
│ │ ├── 🆕 sandwich-bot-solidity-implementation.md
│ │ ├── 🆕 sandwich-bot-typescript-implementation.md
│ │ ├── 🆕 sandwich-bot-rust-implementation.md
│ │ └── 🆕 sandwich-bot-python-implementation.md
│ │
│ ├── examples/ # GitHub repo analyses (41 files)
│ │ ├── github-mouseless0x-rusty-sando.md (857⭐ sandwich bot)
│ │ ├── github-insionCEO-Ethereum-MEV-BOT.md (40⭐ advanced)
│ │ ├── github-i3visio-solana-mev-bot.md (1,100⭐ Solana)
│ │ └── ...
│ │
│ └── discussions/ # Community insights (2 files)
│ ├── reddit-flashloan-viability-discussion.md
│ └── flashloan-vs-mev-analysis.md
│
├── 🆕 bots/ # Educational MEV bots
│ ├── README.md # Complete bot documentation
│ ├── ARCHITECTURE.md # Visual architecture diagrams
│ │
│ ├── sandwich-bot/ # Sandwich attack bot (TypeScript)
│ │ ├── src/
│ │ │ ├── index.ts # Main bot logic
│ │ │ ├── mempoolMonitor.ts # Mempool transaction detection
│ │ │ ├── profitCalculator.ts # Sandwich profit simulation
│ │ │ └── sandwichExecutor.ts # Execution engine
│ │ ├── contracts/
│ │ │ └── SandwichContract.sol # On-chain sandwich contract
│ │ └── README.md # Bot documentation
│ │
│ ├── aave-flashloan-bot/ # Flashloan arbitrage bot (TypeScript)
│ │ ├── src/
│ │ │ ├── index.ts # Main bot logic
│ │ │ ├── priceScanner.ts # Multi-DEX price scanning
│ │ │ ├── opportunityDetector.ts # Arbitrage detection
│ │ │ └── flashloanExecutor.ts # Aave V3 integration
│ │ ├── contracts/
│ │ │ └── FlashloanArbitrage.sol # Flashloan contract
│ │ └── README.md # Bot documentation
│ │
│ ├── aave-frontrun-bot/ # Front-running detection bot (TypeScript)
│ │ ├── src/
│ │ │ ├── index.ts # Main bot logic
│ │ │ ├── mempoolMonitor.ts # Aave transaction detection
│ │ │ └── opportunityAnalyzer.ts # Front-run analysis
│ │ └── README.md # Bot documentation
│ │
│ └── aave-backrun-bot/ # Back-running bot (TypeScript)
│ ├── src/
│ │ ├── index.ts # Main bot logic
│ │ ├── eventMonitor.ts # Aave event monitoring
│ │ └── opportunityDetector.ts # Back-run detection
│ └── README.md # Bot documentation
│
├── contracts/ # Shared smart contracts
├── scripts/ # Deployment scripts
└── test/ # Test suites
Five production-ready implementations with full source code:
| Guide | Language/Stack | Budget | Best For |
|---|---|---|---|
| Roadmap | Multi-language | $1K-5K | Planning & strategy |
| Solidity + TypeScript | Solidity + TS | $1K-5K | Learning full stack |
| TypeScript | Node.js | $1K-5K | Fastest start (1-2 weeks) |
| Rust | Rust + Tokio | $5K-15K | Performance (10-20ms latency) |
| Python | Python | Learning | Understanding concepts |
Each guide includes:
- ✅ Complete working source code
- ✅ Smart contracts (where applicable)
- ✅ Mempool monitoring system
- ✅ Profitability calculator
- ✅ Salmonella (honeypot) detection
- ✅ Deployment instructions
- ✅ Testing strategies
- Flash Loan Providers: Aave V3, dYdX, Uniswap V2/V3, Balancer
- MEV Attacks: Sandwich, front-running, back-running, displacement
- MEV Defenses: Flashbots Protect, CoW Swap, private RPCs, slippage settings
- Programming Languages: Solidity, TypeScript, Rust, Python, Huff, Vyper
- Networks: Ethereum, Arbitrum, Optimism, Base, Polygon, Sui, Solana
- Real Examples: 41 GitHub repositories analyzed (includes rusty-sando, advanced MEV bots)
Unlike promotional content, this repository provides:
- Honest profitability assessments (most MEV bots lose money)
- Realistic competition analysis (professional bots dominate)
- Actual cost breakdowns ($1K-5K for L2, $10K-50K for mainnet)
- Ethical considerations (sandwich attacks harm users)
- Legal warnings (MEV may be regulated)
We welcome contributions! This is a living knowledge base that improves with community input.
-
Add New Documentation
- Found a new tutorial? Add it to
context/tutorials/ - Discovered a new MEV bot repo? Document it in
context/examples/ - Have insights? Share in
context/discussions/
- Found a new tutorial? Add it to
-
Update Existing Content
- Fix outdated information
- Add missing details
- Improve clarity
-
Share Implementation Experience
- Document your bot implementation
- Share lessons learned
- Report actual results (anonymized)
File Format:
**Source:** [URL or "Internal analysis"]
**Date:** [Month Year]
# Title
Content here...File Naming:
source-topic-description.md(e.g.,github-username-repo-name.md)- Use lowercase and hyphens
- Be descriptive but concise
File Placement:
context/core/- Official protocol documentationcontext/tutorials/- How-to guides, strategies, implementationscontext/examples/- GitHub repository analysescontext/discussions/- Community insights, analyses
Pull Request Process:
- Fork this repository
- Create a new branch (
git checkout -b add-new-guide) - Add your documentation file(s)
- Update
context/INDEX.mdwith your new file - Submit a pull request with clear description
What We're Looking For:
- ✅ Up-to-date information (2024-2025 content preferred)
- ✅ Accurate technical details
- ✅ Real-world examples and data
- ✅ Honest assessments (not promotional)
- ✅ Clear explanations
- ✅ Proper attribution/sources
What to Avoid:
- ❌ Promotional content or scams
- ❌ Outdated information (pre-2023 unless historically relevant)
- ❌ Unrealistic profit claims
- ❌ Incomplete or untested code
- ❌ Plagiarized content
| Type | Examples |
|---|---|
| Documentation | New tutorials, protocol updates, best practices |
| Implementation | Your bot code, deployment guides, optimizations |
| Analysis | Profitability studies, competitive analysis, market trends |
| Research | Academic papers, MEV research, algorithm analysis |
| Community | Reddit discussions, Discord insights, Twitter threads |
| Tools | Testing frameworks, simulation tools, monitoring scripts |
-
Start with fundamentals:
- Read
context/core/files to understand protocols - Study
context/tutorials/understanding-sandwich-attacks.md(essential!) - Review
context/discussions/for realistic expectations
- Read
-
Progress to implementation:
- Choose your language (see
context/tutorials/programming-languages-for-flash-loans.md) - Follow relevant implementation guide
- Test on testnets first
- Choose your language (see
-
Study real examples:
- Analyze professional bots in
context/examples/ - Understand what makes them successful
- Learn from their architecture
- Analyze professional bots in
-
Load relevant context into Claude:
@context/core/aave-flash-loans-documentation.md @context/tutorials/understanding-sandwich-attacks.md @context/examples/github-mouseless0x-rusty-sando.md Help me research MEV sandwich attack profitability in 2025 -
Analyze strategies:
@context/discussions/flashloan-vs-mev-analysis.md Compare flash loan arbitrage vs MEV attacks - which is more viable? -
Explore implementations:
@context/tutorials/sandwich-bot-rust-implementation.md Explain the high-performance Rust MEV bot architecture
-
Plan your bot:
@context/tutorials/low-budget-sandwich-bot-roadmap.md Help me plan a $3K budget MEV bot for Arbitrum -
Get implementation help:
@context/tutorials/sandwich-bot-typescript-implementation.md Walk me through building this bot step by step -
Optimize performance:
@context/tutorials/optimizing-gas-fees.md @context/tutorials/importance-of-speed-in-arbitrage.md How do I optimize my bot for sub-50ms latency?
-
Assess viability:
@context/discussions/reddit-flashloan-viability-discussion.md @context/discussions/flashloan-vs-mev-analysis.md Is building a MEV bot worth it in 2025? -
Choose technology stack:
@context/tutorials/programming-languages-for-flash-loans.md Should I use TypeScript or Rust for my MEV bot? -
Evaluate risks:
@context/tutorials/preventing-front-running-attacks.md @context/tutorials/preventing-sandwich-attacks.md What are the main risks and how do I protect myself?
This repository is for EDUCATIONAL PURPOSES ONLY.
⚠️ Legal Risk: MEV extraction may be considered market manipulation in some jurisdictions⚠️ Ethical Concerns: Sandwich attacks directly harm other users⚠️ Financial Risk: Most MEV bots lose money - budget for losses⚠️ Security Risk: Smart contracts handling funds must be audited⚠️ Regulatory Risk: MEV is increasingly scrutinized by regulators
Before deploying any MEV bot:
- Consult legal counsel in your jurisdiction
- Understand the ethical implications
- Budget for complete capital loss
- Test extensively on testnets
- Never commit private keys to repositories
- Get professional security audits
Based on analysis of 76 documentation files:
| Reality | Details |
|---|---|
| High Competition | Sub-5ms detection required for mainnet success |
| Low Success Rate | 5-15% of attempts succeed (even with optimization) |
| Thin Margins | Many opportunities yield <$50 profit after gas |
| High Costs | $1K-5K for L2, $10K-50K for mainnet, plus monthly operating costs |
| Steep Learning Curve | Requires advanced blockchain, DeFi, and MEV knowledge |
| Constant Optimization | Arms race requires continuous improvement |
Most Likely Outcome: Educational experience, break-even or small loss
Success Probability: 5-10% for newcomers
Must-Read Before Building:
understanding-sandwich-attacks.md- 1500+ lines, comprehensivepreventing-front-running-attacks.md- 850+ lines, essential defensesflashloan-vs-mev-analysis.md- Realistic 2025 assessment
Best Implementation Guides:
- Low-Budget Roadmap - Complete $1K-5K plan
- TypeScript Implementation - Fastest start
- Rust Implementation - Best performance
Real-World Examples:
- rusty-sando (857⭐) - Competitive sandwich bot
- Ethereum-MEV-BOT (40⭐) - Advanced graph-based
- Solana MEV (1,100⭐) - Solana flash loans
- Total Files: 76 markdown documents
- Total Content: ~25 MB (~2M+ tokens)
- Coverage: Ethereum, Arbitrum, Optimism, Base, Polygon, Sui, Solana
- Languages: Solidity, TypeScript, Rust, Python, Huff, Vyper, Move
- GitHub Examples: 41 repositories (800+ to 10 stars)
- Last Updated: November 2025
- Maintenance: Active (contributions welcome!)
Have questions? Use this repository with Claude:
@context/INDEX.md
I want to [your goal here], where should I start?
Found an issue? Open a GitHub issue or submit a pull request.
Want to discuss? Join Flashbots Discord or r/defi on Reddit.
This repository contains documentation and educational content from various sources:
- Original content (implementation guides, analyses): MIT License
- Curated documentation: See individual file headers for source attribution
- Code examples: See respective licenses in source repositories
When contributing: Ensure you have rights to share the content and provide proper attribution.
This knowledge base compiles information from:
- Official protocol documentation (Aave, Flashbots, Uniswap)
- 41 open-source GitHub repositories
- Community discussions (Reddit, Discord)
- Professional guides (Solulab, TAS, Sahm Capital)
- Academic research and MEV studies
Special thanks to:
- rusty-sando (857⭐) - Excellent MEV bot reference
- Ethereum-MEV-BOT (40⭐) - Advanced implementation
- The Flashbots team for MEV research and tools
- The DeFi community for open-source contributions
- Browse the documentation: Start with
context/INDEX.md - Choose your path:
- Learning? →
understanding-sandwich-attacks.md - Building? →
low-budget-sandwich-bot-roadmap.md - Researching? →
flashloan-vs-mev-analysis.md
- Learning? →
- Use with Claude: Reference files using
@path/to/file.mdsyntax - Contribute: Submit PRs to improve the knowledge base
Flash Million - Comprehensive Flash Loan & MEV Knowledge Base
Documentation • Implementation Guides • Architecture • Contribute
Made with 📚 for in-depth Claude discussions about DeFi, MEV, and flash loans