Initial commit: Electrum Telegram wallet bot with Tor support

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-26 16:44:21 +00:00
commit ab537a8f73
15 changed files with 1663 additions and 0 deletions
@@ -0,0 +1,243 @@
+# ربات کیف‌پول آنلاین
+
+یک ربات تلگرام خودمیزبان برای مدیریت کیف‌پول‌های بیت‌کوین با استفاده از Electrum. طراحی‌شده برای کیف‌پول‌های فقط-تماشا (xpub) با پشتیبانی از امضای آفلاین (air-gapped).
+
+## قابلیت‌ها
+
+- کیف‌پول جداگانه برای هر کاربر
+- بازیابی کیف‌پول فقط-تماشا از xpub
+- نمایش موجودی (تأییدشده / تأییدنشده)
+- دریافت آدرس
+- ساخت تراکنش امضانشده (PSBT) با انتخاب کارمزد
+- تغییر واحد: BTC / mBTC / ساتوشی
+- پشتیبانی از زبان فارسی و انگلیسی
+- کیبورد ثابت در پایین چت
+- پشتیبانی اختیاری از Tor (اتصال از طریق .onion به سرور عمومی یا نود شخصی)
+
+---
+
+## پیش‌نیازها
+
+- یک سرور لینوکسی با Docker و Docker Compose نصب‌شده
+- توکن ربات تلگرام (از [@BotFather](https://t.me/BotFather))
+- شناسه کاربری تلگرام شما (از [@userinfobot](https://t.me/userinfobot))
+
+---
+
+## راه‌اندازی سرور (گام‌به‌گام)
+
+### ۱. کلون کردن مخزن
+
+```bash
+git clone https://git.goyban.com/goyban/telegtrum_bot.git
+cd telegtrum_bot
+```
+
+### ۲. ساخت فایل `.env`
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+مقادیر را پر کنید:
+
+```
+ELECTRUM_VERSION=4.7.2
+TELEGRAM_BOT_TOKEN=توکن_ربات_شما
+```
+
+### ۳. افزودن شناسه کاربری تلگرام به لیست کاربران مجاز
+
+```bash
+nano allowed_users.txt
+```
+
+یک خط به این فرمت اضافه کنید:
+
+```
+123456789, علی
+```
+
+شناسه کاربری خود را می‌توانید با ارسال پیام به [@userinfobot](https://t.me/userinfobot) در تلگرام پیدا کنید.
+
+### ۴. ساخت و راه‌اندازی کانتینر
+
+```bash
+docker compose up -d --build
+```
+
+این دستور:
+- ایمیج Docker با Electrum نصب‌شده را می‌سازد
+- دیمن Electrum را راه‌اندازی می‌کند
+- ربات تلگرام را اجرا می‌کند
+
+### ۵. بررسی لاگ‌ها
+
+```bash
+docker compose logs -f
+```
+
+باید پیام `Electrum daemon started. Launching bot...` را ببینید.
+
+---
+
+## حالت Tor
+
+حالت Tor، Electrum را از طریق شبکه Tor اجرا می‌کند. از یک فایل Docker Compose و Dockerfile جداگانه استفاده می‌کند تا راه‌اندازی استاندارد تحت تأثیر قرار نگیرد.
+
+### راه‌اندازی
+
+```bash
+cp .env.tor.example .env
+nano .env
+```
+
+`TELEGRAM_BOT_TOKEN` را پر کنید و یکی از حالت‌های اتصال را انتخاب کنید:
+
+**گزینه الف — نود Electrum شخصی از طریق Tor:**
+
+```
+ELECTRUM_SERVER=yournode123.onion:50001:t
+```
+
+**گزینه ب — سرور عمومی .onion (پیش‌فرض، نیاز به تنظیم اضافه ندارد):**
+
+`ELECTRUM_SERVER` را خالی بگذارید. ربات به `electrums3lojbuj.onion:50001:t` وصل می‌شود. برای تغییر از `ELECTRUM_ONION_SERVER` استفاده کنید.
+
+### راه‌اندازی
+
+```bash
+docker compose -f docker-compose.tor.yml up -d --build
+```
+
+### نکات
+
+- Tor داخل همان کانتینر اجرا می‌شود — نیازی به سرویس جداگانه نیست.
+- کانتینر صبر می‌کند تا SOCKS proxy آماده شود، سپس Electrum را راه‌اندازی می‌کند.
+- داده‌های کیف‌پول در یک volume جداگانه (`electrum-tor-data`) ذخیره می‌شود.
+- حرف `t` در آدرس سرور به معنای TCP است — رمزنگاری توسط لایه Tor انجام می‌شود نه SSL.
+
+---
+
+## به‌روزرسانی ربات
+
+فایل `bot.py` به‌صورت volume سوار شده، پس بدون نیاز به rebuild می‌توانید آن را تغییر دهید:
+
+```bash
+# ویرایش bot.py، سپس:
+docker compose restart
+# یا برای حالت Tor:
+docker compose -f docker-compose.tor.yml restart
+```
+
+برای به‌روزرسانی Electrum یا پکیج‌های سیستم:
+
+```bash
+docker compose up -d --build
+# یا برای حالت Tor:
+docker compose -f docker-compose.tor.yml up -d --build
+```
+
+---
+
+## افزودن یا حذف کاربران مجاز
+
+فایل `allowed_users.txt` را ویرایش کرده و ریستارت کنید:
+
+```bash
+nano allowed_users.txt
+docker compose restart
+```
+
+---
+
+## ذخیره‌سازی داده‌ها
+
+داده‌های کیف‌پول در یک volume نام‌دار Docker در مسیر `/root/.electrum` داخل کانتینر ذخیره می‌شود و در ریستارت‌ها و rebuild‌ها باقی می‌ماند.
+
+| حالت | نام volume |
+|---|---|
+| استاندارد | `electrum-data` |
+| Tor | `electrum-tor-data` |
+
+برای پشتیبان‌گیری (حالت استاندارد):
+
+```bash
+docker run --rm -v electrum-data:/data -v $(pwd):/backup debian:bookworm-slim \
+  tar czf /backup/electrum-backup.tar.gz -C /data .
+```
+
+---
+
+## راهنمای استفاده از ربات
+
+### شروع کار
+
+ربات را در تلگرام باز کنید و هر پیامی ارسال کنید. یک کیبورد ثابت در پایین چت با تمام دکمه‌ها نمایش داده می‌شود.
+
+### افزودن کیف‌پول (Add Wallet)
+
+وارد کردن کیف‌پول فقط-تماشا از xpub:
+
+1. روی **Add Wallet** بزنید
+2. نام کیف‌پول را وارد کنید
+3. xpub خود را پیست کنید
+4. رمز عبور تعیین کنید (حداقل ۸ کاراکتر، شامل حرف بزرگ، کوچک و عدد)
+
+### لیست (List)
+
+نمایش تمام کیف‌پول‌های شما.
+
+### بارگذاری (Load)
+
+بارگذاری یک کیف‌پول برای فعال‌سازی:
+
+1. روی **Load** بزنید
+2. کیف‌پول را انتخاب کنید (اگر فقط یک کیف‌پول دارید، خودکار انتخاب می‌شود)
+3. رمز عبور کیف‌پول را وارد کنید
+
+### موجودی (Balance)
+
+نمایش موجودی تأییدشده و تأییدنشده کیف‌پول فعال.
+
+با دکمه‌های inline زیر موجودی می‌توانید بین **BTC**، **mBTC** و **ساتوشی** تغییر دهید.
+
+### دریافت (Receive)
+
+نمایش آدرس دریافت جدید برای کیف‌پول فعال.
+
+### ارسال (Send)
+
+ساخت تراکنش امضانشده (PSBT) برای امضای آفلاین:
+
+1. روی **Send** بزنید
+2. منبع کارمزد را انتخاب کنید: **Electrum** (پیشنهادی) یا **mempool.space** (زنده)
+3. نرخ کارمزد را به صورت sat/vB وارد کنید
+4. رمز عبور کیف‌پول را وارد کنید
+5. آدرس گیرنده را وارد کنید
+6. مقدار را وارد کنید (بر اساس واحد انتخابی)
+7. تراکنش امضانشده را به‌صورت کد و فایل `.txt` دریافت کنید
+8. آن را با کیف‌پول آفلاین خود امضا کنید، سپس از **Broadcast** استفاده کنید
+
+### بستن (Close)
+
+کیف‌پول فعال را از دیمن Electrum خارج می‌کند.
+
+### زبان
+
+روی **🌐 Language** بزنید تا بین فارسی و انگلیسی تغییر دهید.
+
+---
+
+## عیب‌یابی
+
+**ربات پاسخ نمی‌دهد:** لاگ‌ها را با `docker compose logs -f` بررسی کنید. مطمئن شوید توکن ربات درست است و کانتینر در حال اجراست.
+
+**"شما مجاز نیستید":** شناسه کاربری تلگرام شما در `allowed_users.txt` نیست. آن را اضافه کرده و ریستارت کنید.
+
+**خطای کیف‌پول بارگذاری‌نشده:** قبل از بررسی موجودی، دریافت یا ارسال، از **Load** استفاده کنید.
+
+**دیمن شروع نمی‌شود:** کانتینر lockfile را هنگام راه‌اندازی خودکار حذف می‌کند. اگر مشکل ادامه داشت، `docker compose restart` را امتحان کنید.
+
+**حالت Tor — Electrum وصل نمی‌شود:** bootstrap اولیه Tor تا ۳۰ ثانیه طول می‌کشد. لاگ‌ها را با `docker compose -f docker-compose.tor.yml logs -f` بررسی کنید.