# تله‌گتروم (Telegtrum)

**تلگرام + الکترום** — یک ربات تلگرام خودمیزبان برای مدیریت کیف‌پول‌های بیت‌کوین با Electrum.

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

---

## مدل امنیتی — این بخش را حتماً بخوانید

| | |
|---|---|
| **سرور هیچ کلید خصوصی ندارد** | شما فقط **xpub** وارد می‌کنید. قابلیت تماشا دارد، نه خرج کردن. |
| **خرج کردن نیازمند دستگاه آفلاین است** | ربات تراکنش امضانشده می‌سازد؛ شما آن را جای دیگر امضا و برای انتشار برمی‌گردانید. |
| **دسترسی به‌صورت پیش‌فرض بسته است** | فقط شناسه‌های تلگرامی که شما تعیین کنید اجازه دارند. فهرست خالی یعنی هیچ‌کس اجازه ندارد. |
| **اطلاعات حساس از چت پاک می‌شوند** | رمز کیف‌پول و xpub بلافاصله پس از خوانده‌شدن حذف می‌شوند. |
| **کیف‌پول هر کاربر جداست** | هر کاربر پوشهٔ مخصوص خود را دارد و نام‌ها اعتبارسنجی می‌شوند تا کسی به فایل‌های دیگری دسترسی پیدا نکند. |

**در برابر چه چیزهایی محافظت نمی‌کند.** هر کسی که به حساب تلگرام شما دسترسی داشته باشد می‌تواند موجودی و آدرس‌ها را ببیند و تراکنش بسازد (اما نمی‌تواند امضا کند). هر کسی که دسترسی root روی سرور داشته باشد می‌تواند فایل‌های کیف‌پول را بخواند و در لحظهٔ اجرای دستور Electrum رمز کیف‌پول را در فهرست پردازه‌ها ببیند — پس سرور را قابل‌اعتماد نگه دارید و فهرست مجاز را کوتاه. xpub شما یک راز حریم خصوصی است: هر کس آن را داشته باشد تمام تاریخچهٔ تراکنش‌های شما را برای همیشه می‌بیند.

---

## راه‌اندازی سریع (پیشنهادی)

بدون کلون کردن مخزن و بدون build. فقط دو فایل و یک دستور.

```bash
mkdir telegtrum && cd telegtrum

curl -O https://git.goyban.com/goyban/telegtrum_bot/raw/branch/main/docker-compose.deploy.yml
curl -o .env https://git.goyban.com/goyban/telegtrum_bot/raw/branch/main/.env.deploy.example

nano .env          # توکن ربات و شناسه کاربری تلگرام خود را وارد کنید
docker compose -f docker-compose.deploy.yml up -d
docker compose -f docker-compose.deploy.yml logs -f
```

فایل `.env` به دو مقدار نیاز دارد:

```dotenv
TELEGRAM_BOT_TOKEN=123456:ABC...      # از @BotFather
ALLOWED_USERS=123456789               # از @userinfobot، برای چند نفر با کاما جدا کنید
```

اگر `ALLOWED_USERS` تنظیم نشده باشد، compose اجرا نمی‌شود — به‌جای اینکه رباتی بالا بیاید که هیچ‌کس نتواند از آن استفاده کند.

باید پیام `Electrum daemon started. Launching bot...` را ببینید. سپس در تلگرام به ربات پیام دهید و **Add Wallet** را بزنید.

### به‌روزرسانی

```bash
docker compose -f docker-compose.deploy.yml pull
docker compose -f docker-compose.deploy.yml up -d
```

اطلاعات کیف‌پول در ولوم `telegtrum-data` باقی می‌ماند و با به‌روزرسانی از بین نمی‌رود.

---

## پیش‌نیازها

- یک سرور لینوکسی با 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
cp .env.example .env && nano .env
docker compose up -d --build
```

در این حالت فایل `bot.py` به‌صورت read-only مانت می‌شود، پس می‌توانید آن را ویرایش کنید و فقط `docker compose restart` بزنید.

### فهرست کاربران مجاز: فایل یا متغیر محیطی

هر دو کار می‌کنند؛ اگر هر دو را استفاده کنید، با هم ادغام می‌شوند.

**متغیر محیطی** (ساده‌ترین راه — نیازی به مانت فایل نیست):
```dotenv
ALLOWED_USERS=123456789,987654321
```

**فایل** — `allowed_users.txt`، هر کاربر در یک خط، به شکل `id, Name`:
```bash
cp allowed_users.txt.example allowed_users.txt
```
```
123456789, Alice
```

> اگر `allowed_users.txt` را مانت کنید ولی فایل وجود نداشته باشد، داکر بی‌سروصدا یک **پوشه** به‌جای آن می‌سازد و هیچ‌کس نمی‌تواند وارد شود. اکنون کانتینر این حالت را تشخیص می‌دهد و با پیام روشن متوقف می‌شود.

### انتشار ایمیج جدید

```bash
./push.sh            # نسخه از فایل VERSION خوانده می‌شود
./push.sh 1.0.1      # یا نسخه را مستقیم بدهید
```

---

## حالت‌های اتصال

### استاندارد — سرورهای عمومی Electrum

حالت پیش‌فرض. برای اتصال فقط به یک سرور مشخص:

```dotenv
ELECTRUM_SERVER=192.168.1.100:50001:t
```

### محلی / Umbrel — نود شخصی شما

```bash
cp .env.example .env    # مقادیر TELEGRAM_BOT_TOKEN و UMBREL_IP را تنظیم کنید
docker compose -f docker-compose.local.yml up -d --build
```

> آدرس `umbrel.local` داخل کانتینر **کار نمی‌کند** — mDNS فقط روی خود میزبان در دسترس است. از IP واقعی استفاده کنید، مثلاً `192.168.1.100`.

در اولین اجرا فایل `./electrum-data/config` با همان سرور نوشته می‌شود. اگر فایل از قبل باشد دست نمی‌خورد، پس تغییرات دستی شما باقی می‌مانند.

> اگر وصل نشد، بررسی کنید رشتهٔ سرور در `./electrum-data/config` هنوز به `:t` (یعنی TCP) ختم شود. گاهی Electrum آن را به `:s` (SSL) تغییر می‌دهد. کانتینر را متوقف کنید، برگردانید و دوباره اجرا کنید.

### Tor

```bash
cp .env.tor.example .env
docker compose -f docker-compose.tor.yml up -d --build
```

یا نود onion خودتان را بدهید:
```dotenv
ELECTRUM_SERVER=yournode123.onion:50001:t
```
…یا خالی بگذارید تا از سرور onion عمومی استفاده شود (`electrums3lojbuj.onion:50001:t`، قابل تغییر با `ELECTRUM_ONION_SERVER`).

نکته‌ها:
- Tor داخل همان کانتینر اجرا می‌شود؛ entrypoint قبل از اجرای Electrum منتظر آماده‌شدن پروکسی SOCKS می‌ماند.
- **استعلام کارمزد هم از Tor عبور می‌کند.** از سرویس onion سایت mempool.space استفاده می‌شود، بنابراین بررسی کارمزد نمی‌تواند IP سرور شما را به فعالیت بیت‌کوینی‌تان ربط دهد.
- اطلاعات کیف‌پول در ولوم جداگانه (`electrum-tor-data`) نگهداری می‌شود.
- `:t` یعنی TCP — رمزنگاری را خود Tor انجام می‌دهد و SSL لازم نیست.

---

## کار با ربات

یک کیبورد ثابت در پایین چت نمایش داده می‌شود.

| دکمه | کاری که انجام می‌دهد |
|---|---|
| **Add Wallet** | افزودن کیف‌پول فقط-تماشا: نام ← xpub ← رمز. پیام حاوی xpub پس از خواندن حذف می‌شود. |
| **List** | فهرست کیف‌پول‌های شما. |
| **Load** | فعال‌کردن یک کیف‌پول (رمز می‌خواهد). برای Balance / Receive / Send لازم است. |
| **Balance** | موجودی تأییدشده و تأییدنشده. دکمه‌های شیشه‌ای واحد را بین BTC / mBTC / ساتوشی عوض می‌کنند. |
| **Receive** | یک آدرس دریافت استفاده‌نشدهٔ تازه. |
| **Send** | ساخت تراکنش **امضانشده** — پایین‌تر توضیح داده شده. |
| **Close** | خارج‌کردن کیف‌پول فعال از دیمن. |
| **🌐 Language** | تغییر بین فارسی و انگلیسی. |

نام کیف‌پول می‌تواند شامل حروف، اعداد، فاصله، نقطه، خط تیره و زیرخط باشد (۱ تا ۶۴ کاراکتر) و باید با حرف یا عدد شروع شود. رمز باید حداقل ۸ کاراکتر و شامل حرف بزرگ، حرف کوچک و عدد باشد.

### ارسال

۱. **Send** ← انتخاب منبع کارمزد: **Electrum** یا **mempool.space** (زنده)
۲. نرخ کارمزد را بر حسب sat/vB وارد کنید
۳. رمز کیف‌پول را وارد کنید *(پیام بلافاصله حذف می‌شود)*
۴. آدرس مقصد را وارد کنید
۵. مبلغ را وارد کنید یا **Send Max** را بزنید
۶. تراکنش امضانشده را هم به‌صورت متن و هم فایل `.txt` دریافت می‌کنید
۷. آن را آفلاین امضا کنید — الکترومِ اندروید: *Send ← Paste from clipboard*؛ نسخهٔ دسکتاپ: *Send ← آیکون ابزار ← Read text from file*
۸. **Send ← Broadcast** و تراکنش امضاشده را بچسبانید

---

## پشتیبان‌گیری

همه چیز — کیف‌پول‌ها، تنظیمات و هدرهای بلاک‌چین — در یک ولوم است.

```bash
# حالت راه‌اندازی سریع
docker run --rm -v telegtrum-data:/data -v "$PWD":/backup debian:bookworm-slim \
  tar czf /backup/telegtrum-backup.tar.gz -C /data .
```

| حالت | ولوم |
|---|---|
| راه‌اندازی سریع | `telegtrum-data` |
| ساخت از سورس | `electrum-data` |
| Tor | `electrum-tor-data` |
| محلی / Umbrel | `./electrum-data` (bind mount) |

پشتیبان جای عبارت بازیابی (seed) را نمی‌گیرد. اینها کیف‌پول فقط-تماشا هستند؛ چیزی که واقعاً دارایی شما را برمی‌گرداند، seed روی دستگاه آفلاین شماست.

---

## رفع اشکال

**ربات پاسخ نمی‌دهد** — با `docker compose logs -f` لاگ را ببینید. توکن را بررسی کنید و مطمئن شوید کانتینر مدام ری‌استارت نمی‌شود.

**«شما مجاز به استفاده از این ربات نیستید»** — شناسهٔ شما در `ALLOWED_USERS` یا `allowed_users.txt` نیست. اضافه و ری‌استارت کنید.

**همه رد می‌شوند** — اگر هر دو منبع خالی باشند، کانتینر هنگام اجرا پیام `no allowed users configured` را ثبت می‌کند.

**«کیف‌پولی بارگذاری نشده»** — اول **Load** را بزنید؛ Balance و Receive و Send همگی به کیف‌پول فعال نیاز دارند.

**نام کیف‌پول نامعتبر** — فقط حروف، اعداد، فاصله، نقطه، خط تیره و زیرخط.

**دیمن اجرا نمی‌شود** — entrypoint در هر اجرا فایل قفل قدیمی را پاک می‌کند. اگر باز هم بود، `docker compose restart` بزنید.

**Tor وصل نمی‌شود** — راه‌اندازی اولیهٔ Tor ممکن است حدود ۳۰ ثانیه طول بکشد.

---

## اطمینان از چیزی که اجرا می‌کنید

ایمیج، Electrum را از روی تاربالِ رسمی می‌سازد و **امضای GPG آن را با اثرانگشت‌های پین‌شدهٔ کلیدهای انتشار** (ThomasV و sombernight و Emzy) بررسی می‌کند. اگر امضا نباشد یا اثرانگشت نخواند، build شکست می‌خورد و کیف‌پول تأییدنشده منتشر نمی‌شود.

می‌توانید خودتان با `./push.sh` بازتولیدش کنید — یا فایل [`install.sh`](install.sh) را بخوانید، فقط ۶۰ خط است.