telegtrum_bot/README.fa.md

ربات کیف‌پول آنلاین

یک ربات تلگرام خودمیزبان برای مدیریت کیف‌پول‌های بیت‌کوین با استفاده از Electrum. طراحی‌شده برای کیف‌پول‌های فقط-تماشا (xpub) با پشتیبانی از امضای آفلاین (air-gapped).

قابلیت‌ها

• کیف‌پول جداگانه برای هر کاربر
• بازیابی کیف‌پول فقط-تماشا از xpub
• نمایش موجودی (تأییدشده / تأییدنشده)
• دریافت آدرس
• ساخت تراکنش امضانشده (PSBT) با انتخاب کارمزد
• تغییر واحد: BTC / mBTC / ساتوشی
• پشتیبانی از زبان فارسی و انگلیسی
• کیبورد ثابت در پایین چت
• پشتیبانی اختیاری از Tor (اتصال از طریق .onion به سرور عمومی یا نود شخصی)

---

پیش‌نیازها

• یک سرور لینوکسی با Docker و Docker Compose نصب‌شده
• توکن ربات تلگرام (از @BotFather)
• شناسه کاربری تلگرام شما (از @userinfobot)

---

راه‌اندازی سرور (گام‌به‌گام)

۱. کلون کردن مخزن

git clone https://git.goyban.com/goyban/telegtrum_bot.git
cd telegtrum_bot

۲. ساخت فایل .env

cp .env.example .env
nano .env

مقادیر را پر کنید:

ELECTRUM_VERSION=4.7.2
TELEGRAM_BOT_TOKEN=توکن_ربات_شما

۳. افزودن شناسه کاربری تلگرام به لیست کاربران مجاز

nano allowed_users.txt

یک خط به این فرمت اضافه کنید:

123456789, علی

شناسه کاربری خود را می‌توانید با ارسال پیام به @userinfobot در تلگرام پیدا کنید.

۴. ساخت و راه‌اندازی کانتینر

docker compose up -d --build

این دستور:

• ایمیج Docker با Electrum نصب‌شده را می‌سازد
• دیمن Electrum را راه‌اندازی می‌کند
• ربات تلگرام را اجرا می‌کند

۵. بررسی لاگ‌ها

docker compose logs -f

باید پیام Electrum daemon started. Launching bot... را ببینید.

---

حالت Tor

حالت Tor، Electrum را از طریق شبکه Tor اجرا می‌کند. از یک فایل Docker Compose و Dockerfile جداگانه استفاده می‌کند تا راه‌اندازی استاندارد تحت تأثیر قرار نگیرد.

راه‌اندازی

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 استفاده کنید.

راه‌اندازی

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 می‌توانید آن را تغییر دهید:

# ویرایش bot.py، سپس:
docker compose restart
# یا برای حالت Tor:
docker compose -f docker-compose.tor.yml restart

برای به‌روزرسانی Electrum یا پکیج‌های سیستم:

docker compose up -d --build
# یا برای حالت Tor:
docker compose -f docker-compose.tor.yml up -d --build

---

افزودن یا حذف کاربران مجاز

فایل allowed_users.txt را ویرایش کرده و ریستارت کنید:

nano allowed_users.txt
docker compose restart

---

ذخیره‌سازی داده‌ها

داده‌های کیف‌پول در یک volume نام‌دار Docker در مسیر /root/.electrum داخل کانتینر ذخیره می‌شود و در ریستارت‌ها و rebuild‌ها باقی می‌ماند.

حالت	نام volume
استاندارد	electrum-data
Tor	electrum-tor-data

برای پشتیبان‌گیری (حالت استاندارد):

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 بررسی کنید.