Crypto Escrow Bot para Telegram

Un bot de Telegram para facilitar transacciones de criptomonedas (multi-moneda) de forma segura y no custodial, utilizando depósitos en garantía (escrow) en la blockchain.

---

⚠️ Advertencia de Seguridad Importante

Este proyecto se encuentra en una fase temprana de desarrollo y contiene un fallo crítico de seguridad en su estado actual. La gestión de claves privadas NO ES SEGURA y resultará en la PÉRDIDA PERMANENTE DE FONDOS.

NO UTILICE ESTE BOT PARA TRANSACCIONES REALES. Está destinado únicamente para fines educativos y de desarrollo. La máxima prioridad es rediseñar el sistema de gestión de claves antes de que pueda ser considerado para un uso seguro.

---

1. ¿Qué hace este bot?

Este bot actúa como un intermediario neutral para transacciones entre un comprador y un vendedor. En lugar de confiar en una de las partes, los fondos se bloquean en un mecanismo de escrow directamente en la blockchain.

• Para Bitcoin/Litecoin: Se crea una cartera multi-firma 2-de-3, donde para mover los fondos se requiere la firma de 2 de los 3 participantes (comprador, vendedor o árbitro).
• Para Ethereum/EVM (planeado): Se despliega un contrato inteligente único para cada transacción que retiene los fondos.

El bot gestiona la comunicación y el flujo de la transacción, pero nunca tiene el control total de los fondos, garantizando un proceso descentralizado y seguro.

Características Principales

• Arquitectura Limpia: Separación clara en capas de presentación, lógica de negocio y datos.
• Multi-Moneda: Diseñado con un Patrón Strategy para soportar fácilmente diferentes blockchains (BTC, LTC implementados, EVM, XMR planeados).
• No Custodial: El bot no almacena las claves privadas de los usuarios.
• Persistencia: Usa SQLAlchemy para gestionar la base de datos de usuarios y transacciones.
• Configuración Moderna: Emplea pydantic-settings para una gestión de la configuración robusta y centralizada.

2. Tech-Stack

• Lenguaje: Python 3.10+
• Framework del Bot: python-telegram-bot
• Base de Datos: SQLAlchemy ORM (con SQLite por defecto)
• Interacción Blockchain:
  • python-bitcoinlib para Bitcoin y similares.
  • web3.py (planeado para EVM).
• Contratos Inteligentes: Solidity

3. Instalación y Ejecución

Sigue estos pasos para poner en marcha el bot en un entorno de desarrollo.

1. Clonar el Repositorio:

   git clone https://github.com/EricPeD/escrow-bot-tlg.git
   cd escrow-bot-tlg

2. Crear y Activar un Entorno Virtual:

   python3 -m venv venv
   source venv/bin/activate  # En Windows: venv\Scripts\activate

3. Instalar Dependencias:

   pip install -r requirements.txt

4. Configurar Variables de Entorno:

   • Copia el archivo de ejemplo: cp .env.example .env
   • Edita el archivo .env y añade tus credenciales:
     • TELEGRAM_BOT_TOKEN: El token de tu bot, obtenido de @BotFather en Telegram.
     • ARBITER_PRIVATE_KEY: Una clave privada en formato WIF para la cartera que actuará como árbitro en las transacciones de BTC/LTC. Úsala solo en Testnet.
     • BITCOIN_NETWORK: La red a utilizar (por defecto testnet).

5. Ejecutar el Bot: El comando debe ejecutarse desde el directorio raíz del proyecto para que las importaciones funcionen correctamente.

   python -m src.main

   Si todo está configurado correctamente, verás un mensaje de "Iniciando bot..." en la consola.

4. Guía de Comandos del Bot

• /start: Inicia el bot y te registra en el sistema.
• /help: Muestra la lista de comandos disponibles.
• /escrow @vendedor <cantidad> <token>: Inicia una nueva transacción de escrow.
  • Ejemplo: /escrow @triskis 100000 BTC
• /cancel: Cancela la operación actual.

5. Hoja de Ruta (Roadmap)

1. Refactorización de Seguridad (Prioridad #1): Implementar un flujo donde el bot solicita claves públicas a los usuarios en lugar de generarlas.
2. Implementación de APIs de Blockchain: Completar la integración con APIs de exploradores de bloques para verificar saldos, UTXOs y transmitir transacciones.
3. Servicio de Monitoreo de Depósitos: Crear un job en segundo plano para detectar automáticamente los depósitos en las direcciones de escrow.
4. Implementar Estrategia EVM: Integrar el contrato Escrow.sol con web3.py.
5. Comandos de Liberación y Disputa: Añadir los comandos /release y /dispute para completar el ciclo de la transacción.
6. Añadir Tests: Implementar tests unitarios y de integración.

6. Contribuciones

Las contribuciones son bienvenidas, especialmente para abordar los puntos de la hoja de ruta. Por favor, abre un issue para discutir los cambios que te gustaría hacer.

1. Haz un Fork del proyecto.
2. Crea tu rama de funcionalidad (git checkout -b feature/AmazingFeature).
3. Haz Commit de tus cambios (git commit -m 'Add some AmazingFeature').
4. Haz Push a la rama (git push origin feature/AmazingFeature).
5. Abre un Pull Request.

7. Licencia

Distribuido bajo la Licencia MIT. Ver LICENSE para más información.