Skip to content

DOCUMENTATION_INDEX.md

Latest commit

 

History

History
361 lines (283 loc) · 18.6 KB

DOCUMENTATION_INDEX.md

File metadata and controls

361 lines (283 loc) · 18.6 KB

Documentation Index

Last Updated: 2025-11-15

⚠️ IMPORTANT: The RBF Bot (src/main-rbf.ts) is now the PRIMARY/PRODUCTION bot. The Original Bot (src/index.ts) is LEGACY/DEPRECATED.

Complete index of all documentation for the MiTeddy mint bot.

🗺️ Master Navigation

👉 Index of Indexes ⭐ - START HERE - Master navigation hub for all documentation

Single entry point to navigate all 200+ documents. Use this to find any documentation quickly.

🚀 Quick Start

New to the bot? Start here:

  1. Bot Selection Guide ⭐ - NEW - Which bot to use (RBF vs Original)
  2. RBF Bot Quickstart ⭐ - NEW - Quick start for RBF bot (PRODUCTION)
  3. Getting Started Guide - Complete first-time setup (updated for RBF bot)
  4. Configuration Guide - All configuration options explained (RBF bot first)

📚 Core Documentation

Understanding the Bot

  • Architecture Overview - System design, components, data flow, performance (RBF bot primary)
  • Execution Flow - Step-by-step how the bot works from startup to success (RBF bot flow first)
  • Key Concepts - Core strategies explained:
    • RBF Bot (PRODUCTION): Shotgun RBF, Block-event detection, Receipt-based nonce, Compound gas escalation
    • Original Bot (LEGACY): Battering Ram Mode, Pre-warming, Dual-branch strategy, Time-based spam [DISABLED]
  • Code Structure - Codebase organization, key functions, design patterns (RBF bot structure first)
  • API Reference - Complete API documentation for helper modules, utilities, and analysis components

Running the Bot

Configuration

  • Configuration Guide ⭐ - Complete reference for all environment variables (Version 2.0 - Updated 2025-01-15)
    • RBF bot configuration section (PRODUCTION) - 7 variables
    • Legacy Original bot configuration (DEPRECATED)
    • Advanced configuration section (caching, state, logging, timing, RPC)
  • Timing Guide - Timing setup and optimization [LEGACY - Original bot only, RBF bot doesn't need timing]
  • Early Start Guide - Starting the bot early [LEGACY - Original bot only, RBF bot is block-event driven]

Development Tools

Planning & Tracking

  • Merge Plan - Branch merge strategy and planning (2025-11-12)
    • Merge strategy options
    • Branch management
    • Implementation plan
  • Cursor TODO Log - Session tracking and completed deliverables
    • Task tracking across sessions
    • Completed work log
    • Priority organization

Troubleshooting Guides

  • Balance Issues - Insufficient funds, nuclear budget verification, balance cache
  • RPC Filtering - RPC filter errors, pre-warm configuration, fallback behavior
  • 500k Gas Limit - Why 500k appears instead of 260k default

Reference Guides

  • API Reference ⭐ - Complete API documentation for helper modules, utilities, and analysis components
    • Analysis modules (RPC metrics, simulation results)
    • Helper modules (budget tracker)
    • Utility functions (environment utils, time units)
    • Timing system (block time synthesizer)
  • Gas Limit Persistence - How gas limit hints work and are saved
  • Gas Limit Defaults - Default values and selection logic
  • File System Usage - File operations and module structure
  • Node.js Requirements - Node.js version requirements and upgrade guide

Status & Synthesis Documents ⭐ LATEST (2025-11-14)

Previous Status Documents (2025-11-14)

Analysis & Audits

🔍 Historical Context

  • Master Synthesis - Complete timeline and analysis of bot development
    • All critical incidents and fixes
    • Performance evolution
    • Architecture changes
    • Lessons learned

🧪 Testing & Verification

📊 Analysis & Reports

Documentation Maintenance

Indexes & Maps

Organization & Maintenance

  • Organization Patterns ⭐ - Complete guide to organization patterns and conventions
    • Directory structure patterns
    • File naming conventions
    • Index organization patterns
    • File categorization rules
    • Use this for: Understanding how to organize new files and maintain consistency
  • Documentation Maintenance ⭐ - NEW - Systematic approach to keeping docs updated
    • Change type checklists (refactoring, features, bugs, config, performance, breaking)
    • Documentation templates (session summaries, post-mortems, changelog entries)
    • Update workflow and best practices
    • Automation opportunities
    • Use this for: Maintaining documentation as code changes
  • Documentation Change Log - Track all documentation maintenance activities
    • Records updates, fixes, and improvements
    • Documents maintenance patterns
    • Use this for: Tracking documentation maintenance history
  • Organization Audit 2025-11-13 - Comprehensive organization audit and verification report

Audits

Analysis

📖 Documentation Structure

docs/
├── GETTING_STARTED.md          # First-time setup guide
├── ARCHITECTURE.md              # System design
├── EXECUTION_FLOW.md            # Step-by-step execution
├── CONCEPTS.md                  # Key concepts explained
├── CODE_STRUCTURE.md            # Codebase organization
├── CONFIGURATION_GUIDE.md       # Configuration reference
├── MASTER_SYNTHESIS.md          # Development timeline
├── INDEX_OF_INDEXES.md          # Master navigation hub ⭐
├── DOCUMENTATION_INDEX.md       # This file
├── README.md                     # Documentation overview
├── guides/                       # User guides
│   ├── GUIDES_INDEX.md          # Complete guides index
│   ├── QUICK_START_NOW.md
│   ├── RUNBOOK.md
│   ├── TIMING_GUIDE.md
│   ├── GIT_CLI_BEST_PRACTICES.md
│   └── ...
├── audits/                       # Audit reports
│   ├── AUDIT_INDEX.md           # Complete audit index
│   └── ...
├── analysis/                     # Analysis reports
│   ├── ANALYSIS_INDEX.md        # Complete analysis index
│   └── ...
├── prompts/                      # AI agent prompts
│   ├── CHATGPT_DEEP_RESEARCH_PROMPT_2025-11-13.md
│   ├── CODEX_NEW_AGENT_PROMPT_2025-11-13.md
│   └── ...
├── research/                     # Research documents
│   ├── RESEARCH_INDEX.md        # Complete research index
│   └── ...
├── CROSS_REFERENCE_MAP.md        # Cross-reference map
├── TIMELINE_INDEX.md             # Timeline index
├── MERGE_PLAN.md                  # Branch merge planning
└── CURSOR_TODO.md                 # Session tracking log

🎯 Reading Paths

For New Users

  1. Getting Started Guide
  2. Configuration Guide
  3. Runbook
  4. Key Concepts (optional, for deeper understanding)

For Developers

  1. Architecture Overview
  2. Code Structure
  3. Execution Flow
  4. Key Concepts

For Troubleshooting

  1. Runbook - Troubleshooting section with pre-run verification checklist
  2. Balance Issues - Insufficient funds, nuclear budget
  3. RPC Filtering - RPC filter errors, configuration
  4. 500k Gas Limit - Gas limit debugging
  5. Configuration Guide - Configuration validation
  6. Analysis reports in analysis/ directory
  7. Post-Mortem Analysis - 11:11 PST window failure analysis

For Understanding History

  1. Master Synthesis - Complete timeline

🔗 External Resources

📝 Documentation Standards

All documentation follows these standards:

  • Clear Structure: Headers, sections, code blocks
  • Examples: Real configuration examples
  • Code Snippets: Syntax-highlighted code
  • Links: Cross-references to related docs
  • Versioning: $12025-11-15 PST

🤝 Contributing

When adding or updating documentation:

  1. Follow Structure: Use existing docs as templates
  2. Cross-Reference: Link to related documentation
  3. Examples: Include real configuration examples
  4. Update Index: Update this index if adding new docs
  5. Version: Include $12025-11-15 PST

Version: 1.4

Recent Updates (2025-11-15):

  • ✅ Comprehensive Documentation Audit: Complete codebase scan and documentation verification
    • Documentation Audit Report 2025-11-15 - Complete audit findings
    • Line count corrections: src/index.ts 4,172 → 3,933 lines (actual count)
    • Configuration guide expansion: Added 20+ missing environment variables
    • RBF bot configuration: Complete section added (11 new variables)
    • Advanced configuration: Caching, state, logging, timing, RPC sections added
    • All source files verified: All modules documented ✅
    • All scripts verified: All package.json scripts documented ✅
    • Module exports verified: All properly used ✅
  • ✅ Configuration Guide Updated: Version 1.1 with comprehensive expansion
    • RBF bot configuration section (11 environment variables)
    • Advanced configuration section (caching, state, logging, timing, RPC)
    • PRE_WARM_STEPS detailed documentation
    • Change history with version tracking

Previous Updates (2025-11-14):

  • ✅ API Reference: Created comprehensive API reference documentation for all helper modules
    • Analysis modules (RPC metrics, simulation results)
    • Helper modules (budget tracker)
    • Utility functions (environment utils, time units)
    • Timing system (block time synthesizer)
  • ✅ Documentation Gaps Filled: Enhanced architecture, code structure, and concepts documentation
    • Added missing helper modules documentation
    • Enhanced time units documentation
    • Added testing framework overview
    • Documented BlockTimeSynthesizer in detail

Previous Updates (2025-11-13):

  • ✅ Complete Documentation Organization: Created comprehensive indexes for all documentation types
    • Guides Index (27 guides organized by category)
    • Audit Index (80+ audits organized by date and type)
    • Analysis Index (80+ analysis reports organized by topic)
    • Research Index (4 research documents)
    • Cross-Reference Map (relationships between all documents)
    • Timeline Index (chronological organization)
  • ✅ Documentation Organization: Created comprehensive audit index, organized prompt files
  • ✅ ChatGPT Audit: Added ChatGPT audit review and findings (2 issues fixed)
  • ✅ Added troubleshooting guides (Balance, RPC Filtering, 500k Gas Limit)
  • ✅ Added reference guides (Gas Limit Persistence, Gas Limit Defaults, File System Usage, Node.js Requirements)
  • ✅ Created comprehensive changelog for November 2025
  • ✅ Updated documentation to reflect gasLimitHint string format change

Previous Updates (2025-11-12):

  • ✅ Documentation updated to reflect initialization improvements (~20x faster)
  • ✅ Added console log preservation feature documentation
  • ✅ Updated execution flow with new main() structure
  • ✅ Added performance metrics and optimization details