🛡️ Flash Crash Mitigator

Bot DeFi de protección automática para posiciones en Kamino Finance (Solana). Monitoreo 24/7, auto-repago al detectar riesgo de liquidación.

---

📋 Descripción General

Flash Crash Mitigator es un bot reactivo escrito en Rust que monitorea una posición (Obligation) específica en Kamino Finance. Cuando el Health Factor (HF) de la posición cae por debajo de 1.2 —señal de liquidación inminente— el bot ejecuta automáticamente un repay parcial, protegiendo el colateral. Todos los eventos se registran en PostgreSQL con tracing estructurado.

⚡ Su hermano Flash Crash Predator (privado) hace lo opuesto: escanea proactivamente TODO Kamino buscando posiciones para liquidar. Este bot defiende; aquel ataca.

🏗️ Arquitectura

┌──────────────────────────────────────┐
│  Solana RPC (Helius)                 │
│  └─ getAccountData cada N segundos   │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│  Monitor Module (Tokio async loop)   │
│  ┌────────────────────────────────┐  │
│  │ 1. Fetch Obligation account    │  │
│  │ 2. Decode health factor        │  │
│  │ 3. HF < 1.2? → trigger repay   │  │
│  └────────────────────────────────┘  │
└──────────────┬───────────────────────┘
               │ HF < threshold
               ▼
┌──────────────────────────────────────┐
│  Executor Module                     │
│  ┌────────────────────────────────┐  │
│  │ 1. Build repay instruction     │  │
│  │ 2. Sign with in-memory keypair │  │
│  │ 3. Send + confirm transaction  │  │
│  └────────────────────────────────┘  │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│  PostgreSQL + Tracing                │
│  └─ Eventos, health factors, tx ids  │
└──────────────────────────────────────┘

⚡ Funcionalidades Principales

• Monitoreo Continuo: Loop asíncrono con Tokio consultando la Obligation account on-chain
• Detección Temprana: Dispara repay cuando HF < 1.2 (configurable), antes de que otros liquidadores actúen
• Ejecución Automática: Construye y firma la instrucción repay directamente, sin intervención humana
• Keypair en Memoria: La clave privada nunca toca disco — se inyecta como bytes al inicio
• Persistencia: Todos los eventos, health factors y transacciones se registran en PostgreSQL
• Observabilidad: Tracing estructurado con niveles, filtros por módulo, timestamps

🛠️ Stack Tecnológico

Capa	Tecnología
Lenguaje	Rust (edition 2021, tokio async)
Blockchain	Solana (solana-client 1.18, solana-sdk, spl-token)
Protocolo	Kamino Finance
Base de Datos	PostgreSQL (sqlx 0.8, conexiones TLS nativas)
Observabilidad	tracing + tracing-subscriber (env-filter)
Build	Perfil release optimizado (opt-level=3, LTO, strip)
Deploy	Docker Compose + VPS

🚀 Quick Start

# 1. Clonar
git clone https://github.com/Jorchspace/flash-crash-mitigator.git
cd flash-crash-mitigator

# 2. Configurar .env
cp .env.example .env
# Editar: RPC_URL, KEYPAIR_BYTES, OBLIGATION_ID, POSTGRES_URL

# 3. Ejecutar con Docker
docker compose up -d

# 4. O compilar y ejecutar nativo (requiere Rust toolchain)
cargo build --release
./target/release/mitigator

📂 Estructura del Proyecto

flash-crash-mitigator/
├── Cargo.toml              # Dependencias Rust
├── Dockerfile              # Imagen multi-stage
├── docker-compose.yml      # App + PostgreSQL
├── migrations/
│   └── 001_init.sql        # Schema inicial
├── src/
│   ├── main.rs             # Entry point, loop principal
│   ├── config.rs           # Carga de .env
│   ├── monitor.rs          # Lógica de monitoreo HF
│   ├── executor.rs         # Construcción y envío de repay tx
│   └── db.rs               # Conexión y queries PostgreSQL
└── .env.example            # Template de variables

⚙️ Variables de Entorno

Variable	Descripción
RPC_URL	URL del nodo Solana RPC (Helius recomendado)
KEYPAIR_BYTES	Array de bytes de la keypair (formato JSON)
OBLIGATION_ID	Pubkey de la Obligation account a monitorear
LENDING_MARKET_ID	Pubkey del Lending Market de Kamino
REPAY_RESERVE_ID	Pubkey de la Reserve para el repay
POSTGRES_URL	URL de conexión PostgreSQL
HF_THRESHOLD	Health Factor umbral (default: 1.2)
POLL_INTERVAL_SECS	Intervalo de polling en segundos

🔬 Cómo Funciona

1. Inicio: Carga configuración, decodifica keypair en memoria, conecta a PostgreSQL
2. Loop: Cada POLL_INTERVAL_SECS, consulta la Obligation account vía RPC
3. Decode: Extrae el Health Factor de la respuesta on-chain
4. Evalúa: Si HF < HF_THRESHOLD → construye instrucción repay
5. Ejecuta: Firma la transacción con la keypair en memoria, envía, confirma
6. Registra: Inserta evento en PostgreSQL con HF, tx signature, timestamp
7. Duerme: Espera el intervalo configurado, repite

🚀 Estado Actual

En desarrollo activo. Lógica core de monitoreo y repay funcional. Dockerizado con PostgreSQL. Próximos pasos: tests de integración contra devnet, alertas Telegram, dashboard de eventos.

---

Construido por Jorch | Jorch Lab — 2026