{"id":51476005,"url":"https://github.com/alberto2005-coder/novaescrow","last_synced_at":"2026-07-06T21:01:07.540Z","repository":{"id":358690047,"uuid":"1242606411","full_name":"alberto2005-coder/NovaEscrow","owner":"alberto2005-coder","description":"A state-of-the-art, fully automated multi-chain cryptocurrency escrow bot for Discord. Supports BTC, LTC, SOL, ETH, USDT, and USDC with dynamic deterministic wallet derivation, AES key encryption, real-time blockchain monitoring, and a built-in reputation rating system.","archived":false,"fork":false,"pushed_at":"2026-05-18T15:26:10.000Z","size":121,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T17:30:46.738Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alberto2005-coder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-18T15:24:05.000Z","updated_at":"2026-05-18T15:26:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alberto2005-coder/NovaEscrow","commit_stats":null,"previous_names":["alberto2005-coder/novaescrow"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/alberto2005-coder/NovaEscrow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alberto2005-coder%2FNovaEscrow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alberto2005-coder%2FNovaEscrow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alberto2005-coder%2FNovaEscrow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alberto2005-coder%2FNovaEscrow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alberto2005-coder","download_url":"https://codeload.github.com/alberto2005-coder/NovaEscrow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alberto2005-coder%2FNovaEscrow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35205739,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-06T21:01:06.377Z","updated_at":"2026-07-06T21:01:07.496Z","avatar_url":"https://github.com/alberto2005-coder.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔒 NovaEscrow — Multi-Chain Discord Escrow Bot\n\n[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg?style=for-the-badge\u0026logo=python)](https://www.python.org)\n[![Discord.py](https://img.shields.io/badge/discord.py-2.3%2B-5865F2.svg?style=for-the-badge\u0026logo=discord)](https://discordpy.readthedocs.io/)\n[![License](https://img.shields.io/badge/License-Alberto_Ortiz-orange.svg?style=for-the-badge)](LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge)](https://github.com/)\n\n**NovaEscrow** is a state-of-the-art, fully automated multi-chain cryptocurrency escrow bot designed for Discord communities. It enables secure, trustless Peer-to-Peer (P2P) trading of cryptocurrencies directly within private channels, backed by real-time blockchain monitoring.\n\n---\n\n## 🚀 Key Features\n\n* **🌐 Multi-Chain Integration:** Supports native transactions and tokens across multiple major blockchains:\n  * **Bitcoin (BTC)** \u0026 **Litecoin (LTC)** (Legacy \u0026 Bech32 format).\n  * **Ethereum (ETH)** \u0026 **ERC-20 Tokens** (USDT \u0026 USDC).\n  * **Solana (SOL)** (Native token transfers).\n* **🔑 Deterministic Wallet Derivation:** Dynamically derives unique, single-use escrow addresses for every single deal from a single `WALLET_MASTER_KEY` seed, utilizing cryptographic hashing and salt techniques.\n* **🛡️ Fernet Private Key Encryption:** All Derived Private Keys are strongly encrypted in memory using AES-128 in CBC mode with HMAC-SHA256 (Fernet) ensuring that private keys are never handled or stored in plain-text.\n* **🤖 Automatic Blockchain Verification:** Continuous background workers track the blockchain status using direct RPC nodes (Ethereum Web3, Solana Web3, and BlockCypher APIs) to detect incoming deposits automatically.\n* **⚖️ Dual-Signature Release \u0026 Dispute System:**\n  * Fund release requires confirmation from both the Buyer (Sender) and Seller (Receptor).\n  * Built-in dispute mechanism allows administrators to step in as mediators and execute refunds or payouts.\n* **📈 Reputation \u0026 Trading Profiles:** Tracks user statistics including completed trade counts, total trading volume (USD), average star-ratings, and written reviews.\n* **💼 Internal Wallet System:** Allows users to maintain an internal trading balance to execute instant, gas-free trades or withdraw funds to their external wallets at any time.\n\n---\n\n## 📊 Secure Deal Flow\n\n```mermaid\nsequenceDiagram\n    autonumber\n    actor Buyer as 📤 Enviador (Buyer)\n    actor Seller as 📥 Receptor (Seller)\n    actor Bot as 🤖 NovaEscrow Bot\n    actor Admin as ⚖️ Mediador (Admin)\n\n    Buyer-\u003e\u003eBot: /setup \u0026 Clic \"Iniciar Deal\"\n    Note over Bot: Crea canal de ticket privado\n    Bot-\u003e\u003eBuyer: Solicita agregar contraparte\n    Buyer-\u003e\u003eBot: Agrega a Contraparte (Seller)\n    Note over Bot: Concede permisos al canal\n    Buyer-\u003e\u003eBot: Selecciona Rol (Enviador)\n    Seller-\u003e\u003eBot: Selecciona Rol (Receptor)\n    Buyer-\u003e\u003eBot: Especifica cantidad \u0026 Cripto (ej. 0.5 SOL)\n    Seller-\u003e\u003eBot: Confirma cantidad \u0026 provee dirección de Retiro\n    Note over Bot: Genera dirección de Escrow Única\n    Bot-\u003e\u003eBuyer: Provee dirección de Escrow\n    Buyer-\u003e\u003eBot: Envía fondos a dirección de Escrow\n    loop Monitoreo en background\n        Bot-\u003e\u003eBot: Escanea saldo de blockchain\n    end\n    Bot-\u003e\u003eSeller: 🎉 Depósito Detectado \u0026 Bloqueado en Escrow\n    Note over Bot: Espera confirmación de entrega del servicio/producto\n    Buyer-\u003e\u003eBot: Clic \"Confirmar Liberación\"\n    Seller-\u003e\u003eBot: Clic \"Confirmar Liberación\"\n    Note over Bot: Transfiere fondos reales de Escrow a Seller\n    Bot-\u003e\u003eSeller: Fondos enviados exitosamente\n    Bot-\u003e\u003eBuyer: Solicita calificar con estrellas\n    Bot-\u003e\u003eSeller: Solicita calificar con estrellas\n    Note over Bot: Actualiza reputación \u0026 cierra el canal\n```\n\n---\n\n## 📂 Project Structure\n\nThe project follows a clean, highly decoupled **Modular Cog-based Architecture** to ensure maximum maintainability:\n\n```text\nNovaEscrow/\n│\n├── src/\n│   ├── database/               # Database interactions (SQLite / Aiosqlite)\n│   │   └── manager.py          # Tables initialization, profile queries, and balance updates\n│   │\n│   ├── services/               # Core Blockchain Integrations\n│   │   └── wallet.py           # Keys derivation, transaction building, and balance verification\n│   │\n│   ├── utils/                  # Shared Utility helpers\n│   │   └── logging.py          # Structured audit logging channel\n│   │\n│   ├── ui/                     # Discord Interactive UI Layer\n│   │   └── views.py            # Buttons, Modals, Dropdowns, and Background monitoring tasks\n│   │\n│   └── cogs/                   # Modular Slash Command Domains\n│       ├── escrow.py           # Commands: /setup, /cerrar, /info, /stats, /perfil\n│       └── balance.py          # Commands: /balance, /depositar, /retirar\n│\n├── main.py                     # Clean, lightweight application entry point\n├── pyproject.toml              # Project dependencies and packaging\n├── .env.example                # Template for server-side environments\n└── README.md                   # This documentation\n```\n\n---\n\n## 🛠️ Installation \u0026 Setup\n\n### 1. Prerequisites\nEnsure you have Python 3.10 or higher installed. It is highly recommended to use [uv](https://github.com/astral-sh/uv) or `pip` to manage virtual environments.\n\n### 2. Clone the Repository\n```bash\ngit clone https://github.com/your-username/NovaEscrow.git\ncd NovaEscrow\n```\n\n### 3. Install Dependencies\n```bash\npip install -e .\n```\n\n### 4. Configure Environment Variables\nCopy `.env.example` to `.env` and fill in the required keys:\n```bash\ncp .env.example .env\n```\n\nEdit the `.env` file:\n```env\n# Discord Configuration\nDISCORD_TOKEN=your_discord_bot_token_here\nLOG_CHANNEL_ID=your_discord_log_channel_id_here\n\n# Blockchain Configuration (Escrow Operations)\nWALLET_MASTER_KEY=your_cryptographically_secure_master_key_here\nINFURA_URL=https://mainnet.infura.io/v3/your_infura_project_id\nSOLANA_RPC=https://api.mainnet-beta.solana.com\nBLOCKCYPHER_TOKEN=your_blockcypher_api_token_here\n```\n\n\u003e [!IMPORTANT]\n\u003e **WALLET_MASTER_KEY:** Keep this value extremely secure. All single-use escrow addresses and private keys are deterministically generated from this key. If lost, escrow funds cannot be retrieved; if leaked, hackers can intercept derived keys. Use a strong secret (the bot will generate one automatically if left empty, but it is best to set a persistent one).\n\n---\n\n## 📊 Bot Slash Commands\n\n### 🛡️ Administration\n* `/setup` - Configures the current channel as the central gateway for starting Escrow deals (requires administrator privileges).\n\n### 👥 Deal Operations\n* `/cerrar` - Cleanly closes and deletes the current active ticket channel (can be triggered by deal participants or server admins).\n\n### 👤 Profile \u0026 Analytics\n* `/perfil [@usuario]` - Displays trading stats (completed deals, reputation stars, trading volume in USD) of a user.\n* `/info` - Shows general bot features, supported cryptocurrencies, and available commands list.\n* `/stats` - Displays global server statistics (total escrow tickets, completed deals, active disputes).\n\n### 💼 Portfolio Management\n* `/balance` - Shows the user's secure internal wallet balances across all supported cryptocurrencies.\n* `/depositar` - Provides a deterministic address to top up the user's internal trading wallet.\n* `/retirar` - Prompts a modal to securely transfer internal wallet funds to an external blockchain address.\n\n---\n\n## 🛡️ Security Best Practices\n\n1. **Deterministic Isolation:** Single-use keypairs are dynamically derived with custom channel IDs and nonces, preventing wallet address reuse across deals.\n2. **Secure Key Loading:** Master keys and Infura/Solana RPC URLs are loaded strictly from the system environment (`.env`) and never hardcoded.\n3. **Audit Trails:** Every event (roles confirmation, deposits, releases, disputes, and withdrawals) publishes comprehensive audit logs to a dedicated administration channel (`LOG_CHANNEL_ID`).\n4. **No Plaintext Private Keys:** Temporary private keys are encrypted instantly upon derivation using AES-128 Fernet encryption, and only decrypted in-memory during transaction signing.\n\n---\n\n## 📄 License\nThis project is licensed under the \"Licencia de Software Libre con Atribución Obligatoria (Licencia Alberto Ortiz)\" - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falberto2005-coder%2Fnovaescrow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falberto2005-coder%2Fnovaescrow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falberto2005-coder%2Fnovaescrow/lists"}