diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..56ffaa1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,37 @@ +# Rust build artifacts +/target/ +**/*.rs.bk + +# Foundry build artifacts +contracts/out/ +contracts/cache/ +contracts/broadcast/ +out/ +cache/ +broadcast/ + +# JS/TS tooling +node_modules/ + +# Environment / secrets +.env +.env.local + +# macOS +.DS_Store + +# Editor +.idea/ +.vscode/ + +# Logs +*.log + +# Markdown policy: only README.md is ever pushed; everything else is local-only. +*.md +!README.md + +# Local-only dev notes and editor configs +.claude/ +docs/context.md +NOTES.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..9d1ae44 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Charon Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..aafddfe --- /dev/null +++ b/README.md @@ -0,0 +1,276 @@ +# Charon + +> Multi-chain, flash-loan-backed liquidation bot — written in Rust. + +[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) +[![Rust](https://img.shields.io/badge/rust-edition_2024-orange.svg)](https://www.rust-lang.org/) +[![Status](https://img.shields.io/badge/status-v0.1%20WIP-yellow.svg)](#roadmap) + +Charon monitors under-collateralized positions across major DeFi lending protocols and executes profitable liquidations using flash loans — **zero upfront capital, zero position risk**. If a liquidation turns out to be unprofitable at execution time, the entire transaction reverts atomically; the only cost is a failed simulation's gas. + +> Named after the mythological ferryman. Charon carries underwater positions to their final destination. + +--- + +## Table of Contents + +- [Status](#status) +- [How it works](#how-it-works) +- [Key features](#key-features) +- [Safety model](#safety-model) +- [Getting started](#getting-started) +- [Configuration](#configuration) +- [Project structure](#project-structure) +- [Roadmap](#roadmap) +- [Contributing](#contributing) +- [License](#license) + +--- + +## Status + +**v0.1 — work in progress.** The foundation is in place: Cargo workspace, normalized types, the `LendingProtocol` trait, a TOML config loader with env-var substitution, and a runnable CLI that validates and reports on the loaded config. Chain listening, health scanning, and on-chain execution arrive in the next phases of the build. + +**Current scope:** Venus Protocol on BNB Chain. Other protocols and chains are on the [roadmap](#roadmap). + +> ⚠️ **Do not run this against mainnet with real funds yet.** Nothing has been battle-tested. Treat v0.1 as development-only. + +--- + +## How it works + +```mermaid +flowchart LR + BNB[BNB Chain
WebSocket]:::chain + + subgraph Core["Charon Core — Rust"] + direction TB + L[Chain Listener] --> A[Venus Adapter] + A --> S[Health Scanner] + P[Price Engine
Chainlink + TWAP] --> S + S --> Pr[Profit Calculator] + Pr --> R[Flash Loan Router] + R --> B[Tx Builder] + end + + subgraph OnChain["On-chain — Solidity"] + direction TB + Liq[CharonLiquidator.sol] + F[Flash Loan Source
Aave V3 Pool] + D[DEX Swap
PancakeSwap / Uniswap V3] + V[Venus Protocol] + Liq --> F + Liq --> V + Liq --> D + end + + BNB --> L + B --> Liq + + classDef chain fill:#0f1e36,stroke:#3b82f6,color:#e2e8f0 +``` + +1. **Listen** — A WebSocket listener receives new blocks and log events from the chain. +2. **Decode** — Protocol adapters normalize raw events into a shared `Position` struct — the rest of the pipeline doesn't care whether the source is Venus, Aave, or anything else. +3. **Price** — A price engine reads live USD prices from Chainlink, with Uniswap V3 TWAPs as a fallback when Chainlink is unavailable or stale. +4. **Scan** — The health scanner recomputes health factors and flags any position that drops below `1.0`. +5. **Estimate** — The profit calculator simulates the full liquidation end-to-end (gas + flash-loan fee + expected DEX slippage) and drops anything below a per-chain USD threshold. +6. **Route** — The flash-loan router picks the cheapest available source (Balancer 0 % → Aave V3 0.05 % → Uniswap V3 pool fee). +7. **Build** — The transaction builder encodes the call, dry-runs it via `eth_call`, signs, and submits (via Flashbots on Ethereum, private RPC on L2s). +8. **Execute** — On-chain, `CharonLiquidator.sol` atomically: flash-borrows → calls the protocol's liquidation entry point → swaps seized collateral back to the debt token → repays the flash loan → forwards profit to the bot's hot wallet. If any step fails, the entire transaction reverts. + +--- + +## Key features + +- **Zero capital required.** Every liquidation is flash-loan-backed. No pre-funded position, no locked inventory. +- **Protocol-agnostic.** Adding a new lending protocol means implementing a single Rust trait (`LendingProtocol`). No changes to scanning, routing, or execution. +- **Multi-chain by design.** A single binary monitors multiple EVM chains in parallel. v0.1 ships BSC; v0.3 expands to Ethereum, Arbitrum, Polygon, Base, and Avalanche. +- **Rust performance.** `tokio` async runtime, lock-free concurrent state via `DashMap`, sub-50 ms block-to-broadcast latency target. Designed to run comfortably on a $5 VPS. +- **Flash-loan atomicity.** Bad slippage, race conditions, and math errors all revert the transaction — the protocol never loses its liquidity, and the bot never loses capital. +- **Open source, MIT licensed.** Community extensions welcome. + +--- + +## Safety model + +Every liquidation has the atomic form: + +``` +borrow (flash) → liquidate → swap → repay flash → profit +``` + +If the chain of operations cannot repay the flash loan in full, the EVM reverts the entire transaction — including the flash borrow itself. Concretely: + +| Failure mode | Outcome | +|---|---| +| Profit estimate was wrong | Tx reverts, flash source gets its capital back, bot pays only gas | +| DEX swap slippage exceeds slippage guard | Tx reverts atomically — no capital change | +| Another bot won the race | `eth_call` simulation catches 99 %+ before submit, so no gas spent | +| Oracle update mid-transaction pushes health back ≥ 1.0 | Tx reverts on the liquidation call | + +**Worst case:** gas for a single failed transaction (typically $0.01–$5 depending on chain). +**Best case:** profit lands in the bot's hot wallet. +**No intermediate case** where bot capital is lost — this is the fundamental guarantee of flash-loan design. + +--- + +## Getting started + +### Prerequisites + +- **Rust** — edition 2024 / `rustc 1.85+`. Install via [rustup.rs](https://rustup.rs/). +- **A BNB Chain RPC endpoint** — `.env.example` ships with public-node defaults (good for light testing, rate-limited in production). For real use, point it at a private endpoint (QuickNode, Ankr, Blast, or your own node). + +### Clone and build + +```bash +# via HTTPS +git clone https://github.com/obchain/Charon.git + +# or via SSH +git clone git@github.com:obchain/Charon.git + +cd Charon +cargo build +``` + +### Configure + +```bash +cp .env.example .env +# edit .env with your RPC endpoints +``` + +### Run + +```bash +cargo run -- --config config/default.toml listen +``` + +Expected output (v0.1 — scanner not wired up yet): + +``` +INFO charon: charon starting up +INFO charon: loading config path=config/default.toml +INFO charon: config loaded chains=1 protocols=1 flashloan_sources=1 liquidators=1 min_profit_usd=5 +INFO charon: listen: not wired up yet — scanner arrives in Day 2 +``` + +For verbose logs, prepend `RUST_LOG=debug`. + +--- + +## Configuration + +Charon reads a TOML config file (default path: `config/default.toml`). Secrets — RPC URLs, keys, API tokens — are referenced as `${ENV_VAR}` placeholders and substituted from the process environment (or a local `.env` file) at load time. + +Example (abridged): + +```toml +[bot] +min_profit_usd = 5.0 # drop opportunities below this threshold +max_gas_gwei = 10 # skip when gas spikes beyond this +scan_interval_ms = 1000 # polling cadence (ms) + +[chain.bnb] +chain_id = 56 +ws_url = "${BNB_WS_URL}" +http_url = "${BNB_HTTP_URL}" + +[protocol.venus] +chain = "bnb" +comptroller = "0xfd36e2c2a6789db23113685031d7f16329158384" + +[flashloan.aave_v3_bsc] +chain = "bnb" +pool = "0x6807dc923806fe8fd134338eabca509979a7e0cb" +``` + +Environment variables expected by the default config: + +| Variable | Purpose | +|---|---| +| `BNB_WS_URL` | BNB Chain WebSocket RPC endpoint | +| `BNB_HTTP_URL` | BNB Chain HTTPS RPC endpoint (for multicall) | + +--- + +## Project structure + +``` +Charon/ +├── crates/ +│ ├── charon-core/ # Shared types, LendingProtocol trait, config loader +│ ├── charon-scanner/ # Chain listener + health-factor scanner (v0.1 WIP) +│ └── charon-cli/ # Command-line binary (`charon`) +├── config/ +│ └── default.toml # Default configuration (Venus on BNB) +├── .env.example # Environment variable template +└── Cargo.toml # Workspace root + shared dependency versions +``` + +Crates planned for later phases: + +- **`charon-protocols/`** — per-protocol adapters (Venus, Aave V3, Compound V3, Morpho, …) +- **`charon-flashloan/`** — flash-loan source router +- **`charon-executor/`** — transaction builder, batcher, gas strategy, nonce manager +- **`charon-telemetry/`** — Prometheus metrics + Telegram alerting +- **`contracts/`** — Foundry workspace housing `CharonLiquidator.sol` + +--- + +## Roadmap + +Tracked on GitHub: [obchain/Charon › Milestones](https://github.com/obchain/Charon/milestones). + +### v0.1 — Venus on BNB *(current)* + +- [x] Cargo workspace + three-crate skeleton +- [x] Core types (`Position`, `LiquidationOpportunity`, `FlashLoanSource`, `SwapRoute`, …) +- [x] `LendingProtocol` trait +- [x] TOML config loader with env-var substitution +- [x] CLI with `--config` flag and `listen` subcommand +- [ ] Venus adapter — fetch positions, compute liquidation params +- [ ] Chainlink price engine (with Uniswap V3 TWAP fallback) +- [ ] Health-factor scanner + near-liquidation cache +- [ ] `CharonLiquidator.sol` (Foundry) + deploy script +- [ ] Flash-loan router (Aave V3 on BSC) +- [ ] DEX swap optimizer (PancakeSwap / Uniswap V3) +- [ ] Transaction builder with `eth_call` simulation +- [ ] Prometheus metrics + Telegram alerts +- [ ] Docker Compose deployment + +### v0.2 — Multi-protocol *(planned)* + +- Aave V3 adapter +- Compound V3 adapter +- Morpho Blue adapter +- Protocol-specific close-factor handling + +### v0.3 — Multi-chain *(planned)* + +- Ethereum Mainnet (with Flashbots bundle submission) +- Arbitrum One +- Polygon PoS +- Base +- Avalanche C-Chain + +--- + +## Contributing + +Contributions are welcome. A few ground rules: + +1. **Open an issue first** for non-trivial changes, so the design can be discussed before code is written. +2. **One logical change per PR.** Keep commits focused and follow conventional titles (`feat(core):`, `fix(scanner):`, `chore:`, etc.). +3. **Respect the crate boundaries.** Protocol changes live in `charon-protocols/`, execution changes in `charon-executor/`. Shared types belong in `charon-core`. +4. **No secrets in the repo — ever.** `.env` is git-ignored. Keep it that way. + +New to the codebase? Check issues tagged [`good first issue`](https://github.com/obchain/Charon/labels/good%20first%20issue). + +--- + +## License + +MIT — see [LICENSE](LICENSE).