EonFlow

High‑performance, modular Telegram‑first trading stack with copy‑trade and sniper capabilities for Ethereum and Base. This repository provides a unified provider layer (Alchemy HTTP/WS), a Telegram control panel (aiogram 3), a minimal FastAPI health/metrics service, and pluggable DEX routing primitives.

Audience: This README balances deep technical detail with accessible explanations so both engineers and non‑technical collaborators can understand and operate the system.

Key Features

Unified Provider Layer — resilient HTTP/WebSocket clients with backoff, heartbeats, and chain‑scoped routing (ETH, Base).
Telegram Panel (UX‑first) — inline keyboards and stateful flows for wallet management, copy/snipe actions, and status.
Deterministic Core — DEX abstractions (dex_base, router_unified) and chain models (chains, accounts) designed to be testable and extendable.
Health & Metrics — lightweight FastAPI app exposing Prometheus counters/gauges and /info for basic diagnostics.
Scriptable Bootstrap — opinionated bootstrap script for first‑run checks and environment validation.
Config‑as‑Data — YAML/JSON examples for infra keys and runtime settings.

The codebase aims to be production‑grade: structured logging (structlog), controlled retries (tenacity), async Web3 providers, and clear separation of concerns.

Repository Structure

EonFlow/
  eonflow.db
  eonflow.log
  launcher.py
  main.py
  main_backup.py
  panel_ui.py
  port_fix.py
  pyproject.toml
  python
  requirements.txt
  start_eonflow.py
  state_store.py
  state_store_ALTERNATIVE.py
  state_store_fix.py
  state_store_patch.py
  ui_render.py
  config/
    config.example.yaml
    keys.example.json
  data/
    follows.json
    positions.json
    settings.json
    trades.json
    wallets.json
  eonflow/
    __init__.py
    main.py
    panel_ui.py
    api/
      server.py
      __pycache__/
        server.cpython-312.pyc
    config/
      .gitignore
      config.example.yaml
      config.yaml
      config_local.py
      config_local.py.backup
      config_local_backup2.py
      config_local_backup_final.py
      config_schema.py
      keys.example.json
      keys.local.json
      __pycache__/
        config_local.cpython-312.pyc
        config_schema.cpython-312.pyc
    core/
      accounts.py
      chains.py
      config_local.py
      config_schema.py
      dex_base.py
      provider.py
      router_unified.py
      state_store.py
      __pycache__/
        accounts.cpython-312.pyc
        chains.cpython-312.pyc
        provider.cpython-312.pyc
        state_store.cpython-312.pyc
    panel/
      python
      ui_handlers.py
      ui_render.py
      ui_state.py
      __pycache__/
        ui_handlers.cpython-312.pyc
        ui_render.cpython-312.pyc
        ui_state.cpython-312.pyc
    telegram_bot/
      bot.py
      __pycache__/
        bot.cpython-312.pyc
    __pycache__/
      __init__.cpython-312.pyc
      main.cpython-312.pyc
  eonflow.egg-info/
    PKG-INFO
    SOURCES.txt
    dependency_links.txt
    requires.txt
    top_level.txt
  scripts/
    bootstrap.py
  __pycache__/
    state_store_patch.cpython-312.pyc
    ui_render.cpython-312.pyc

Notable paths

eonflow/core/* — core abstractions: chains, providers, DEX router, account models, state store.
eonflow/panel/* — aiogram v3 panel logic (handlers, renderer, state manager).
eonflow/telegram_bot/* — Telegram bot bootstrap and runtime.
eonflow/api/server.py — FastAPI app for /healthz, /metrics, and /info.
scripts/bootstrap.py — first‑run checks and local environment setup.
config/*.example.* — configuration templates you should copy and edit.
data/*.json — local JSON state (wallets, trades, positions, follows, settings).

Quick Start

Requirements: Python 3.12+, poetry or pip, an Alchemy account (HTTP + WebSocket keys) for Ethereum/Base, and a Telegram Bot token.

Clone and install

git clone https://github.com/your-org/eonflow.git
cd eonflow
# Option A: pip
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Option B: poetry
poetry install

Configure your environment

cp config/config.example.yaml config/config.yaml
cp config/keys.example.json config/keys.json
# Edit config/config.yaml and config/keys.json with your Alchemy keys and bot token(s)

Run the Telegram bot panel

python -m eonflow.main
# or
python start_eonflow.py

Expose metrics/health (optional)

python -m eonflow.api.server
# visit: http://localhost:8000/healthz  |  /metrics  |  /info

If you prefer a guided setup, run: python scripts/bootstrap.py

Documentation

Architecture — subsystems and data flow.
Setup & Installation — env, dependencies, first run.
Configuration — YAML/JSON schema and examples.
Telegram Panel — UX flows and handler matrix.
API & Metrics — FastAPI endpoints and Prometheus metrics.
Troubleshooting — common errors and fixes.
FAQ — accessible descriptions for non‑engineers.
Glossary — domain terms explained simply.
Contributing — standards, commit style, code review.
Security — secrets handling, keys rotation, reports.

Status

The project ships with a functional stack designed for real‑time Telegram operations. Some files may contain ... placeholders where private logic was redacted. The documented public surface and configuration formats remain stable.

License

No license file was provided. If you intend the project to be Open Source, add an SPDX‑compatible license (e.g., MIT, Apache‑2.0). See docs/CONTRIBUTING.md for guidance.

PreviousAPI & Metrics NextArchitecture