# Общие сведения

> English version: [README.md](README.md)

[ElectrumX](https://github.com/spesmilo/electrumx) — сервер протокола Electrum. Он индексирует цепочку по данным полного узла и отвечает на запросы, которые лёгкий клиент не может обработать сам: история и UTXO произвольного адреса, а также публикация транзакций.

ElectrumX, работающий в docker-контейнере, настраивается переменными окружения.

Репозиторий описывает только развёртывание в docker. Сам ElectrumX устанавливается из зафиксированного тега upstream-репозитория.

# Использование

ElectrumX нужен `bitcoind`, доступный по RPC, в той же сети и без обрезки
цепочки. `DAEMON_URL` — единственная обязательная переменная; `NET` должен
называть ту же сеть, в которой работает демон.

Контейнер отдаёт протокол Electrum на порту **50001** (открытый TCP) и, если
этого требует `SERVICES`, на порту **50002** (TLS). Никакой аутентификации нет,
поэтому держите оба порта во внутренней сети docker или на loopback.
Служебный **RPC** на `localhost:8000` наружу не выходит — им пользуется проверка
состояния контейнера.

## docker-compose

```yaml
services:
  electrumx:
    build:
      context: https://git.bitdeals.org/private/electrumx.git
      dockerfile: ./docker/Dockerfile
    image: registry.bitdeals.org/electrumx
    environment:
      - COIN=Bitcoin
      - NET=regtest
      - DAEMON_URL=http://CHANGE_ME:CHANGE_ME@bitcoind:18443
      - CACHE_MB=400
    ports:
      - 127.0.0.1:50001:50001   # без аутентификации — только loopback
    volumes:
      - electrumxdata:/data

volumes:
  electrumxdata:
```

## docker cli

```sh
docker run -d \
  -e COIN=Bitcoin \
  -e NET=regtest \
  -e DAEMON_URL=http://CHANGE_ME:CHANGE_ME@bitcoind:18443 \
  -e CACHE_MB=400 \
  -p 127.0.0.1:50001:50001 \
  -v electrumxdata:/data \
  registry.bitdeals.org/electrumx
```

Всё, что указано после имени образа, передаётся `electrumx_server`.

## сборка и публикация

Пуш в `main` собирает и публикует образ (`.gitea/workflows/build.yaml`) с тремя
тегами: `<версия>.<sha7>` — для развёртывания, `<версия>` — для чтения глазами,
`latest` — для compose и Watchtower. Вручную, если под рукой есть учётные данные
registry:

```sh
docker build . --file docker/Dockerfile --tag registry.bitdeals.org/electrumx
docker push registry.bitdeals.org/electrumx
```

Другая версия ElectrumX задаётся аргументом сборки — берите тег из
[upstream-репозитория](https://github.com/spesmilo/electrumx/tags):

```sh
docker build . --file docker/Dockerfile \
  --build-arg ELECTRUMX_VERSION=2.0.0 \
  --tag registry.bitdeals.org/electrumx:2.0.0
```

# Параметры

Образы контейнера настраиваются параметрами, передаваемыми при запуске. Все
переменные — собственные переменные ElectrumX, поэтому
[справочник upstream](https://electrumx-spesmilo.readthedocs.io/en/latest/environment.html)
применим без изменений; в таблице перечислены те, которым этот образ задаёт
значения по умолчанию.

|Параметр|Назначение|
|:--------|:-------|
|-p 127.0.0.1:50001|Протокол Electrum поверх открытого TCP. Аутентификации нет — см. «Замечания»|
|-p 127.0.0.1:50002|Протокол Electrum поверх TLS. Отдаётся, только если `SERVICES` содержит `ssl://`|
|-v /data|Каталог данных: индекс и самоподписанный сертификат, если он был создан. Его потеря означает повторную индексацию цепочки|
|-e DAEMON_URL|**Обязательный.** RPC демона, например `http://user:password@bitcoind:8332`. Можно указать несколько через запятую|
|-e COIN|Класс монеты. По умолчанию: `Bitcoin`|
|-e NET|Сеть: `mainnet`, `testnet`, `testnet4`, `signet`, `regtest` или `mutinynet`. Должна совпадать с сетью демона. По умолчанию: `mainnet`|
|-e DB_ENGINE|Хранилище индекса. По умолчанию: `rocksdb` — единственный движок, библиотеки которого есть в образе|
|-e DB_DIRECTORY|Где лежит индекс. По умолчанию: `/data`|
|-e SERVICES|Что обслуживать, через запятую. По умолчанию: `tcp://:50001,rpc://localhost:8000`. Оставьте запись `rpc://` — она нужна проверке состояния|
|-e SSL_CERTFILE, -e SSL_KEYFILE|Сертификат и ключ TLS. По умолчанию: самоподписанная пара создаётся в каталоге данных, если `SERVICES` содержит `ssl://`|
|-e PEER_DISCOVERY|Искать ли другие публичные серверы. По умолчанию: `off` — образ рассчитан на приватный индексатор|
|-e PEER_ANNOUNCE|Объявлять ли себя в сети серверов. По умолчанию: `false`|
|-e CACHE_MB|Кэш индексации. По умолчанию: `1200` (значение ElectrumX). Снижайте для небольшой цепочки, повышайте для ускорения первой индексации mainnet|

# Замечания

- **Аутентификации нет никакой.** Любой, кто дотянулся до 50001 или 50002, может
  запросить произвольный адрес и опубликовать транзакцию. Публикуйте на
  loopback, а если клиенты — контейнеры той же сети, не публикуйте вовсе.
- **Индекс от другого образа не читается.** Здесь rocksdb, а
  `lukechilds/electrumx`, который этот образ заменяет в BitDeals, писал leveldb.
  Подключите пустой том и дайте проиндексировать заново: для regtest и testnet
  это быстро, для mainnet — несколько суток.
- **Демону нужны `txindex=1` и `txospenderindex=1`.** ElectrumX 2.x перед
  началом работы запрашивает `getindexinfo` и завершается с `RuntimeError`,
  называя недостающий индекс — по одному за раз, так что после включения
  `txindex` вы получите то же сообщение про `txospenderindex`. В соседнем
  [образе bitcoind](https://git.bitdeals.org/private/bitcoind) это
  `BITCOIND_TXINDEX=1` и `BITCOIND_TXOSPENDERINDEX=1`; на существующем каталоге
  данных их включение означает переиндексацию демона.
- **Демон не должен быть обрезанным.** Индексация читает каждый блок; узел с
  `-prune` приводит к отказу на середине с сообщением об отсутствующем блоке, а
  не о неверной настройке.
- **`NET` пишется по-электрумовски, а не по-биткойновски.** Демон называет сети
  `main`, `test` и `regtest`, ElectrumX — `mainnet`, `testnet` и `regtest`.
  Точка входа отвергает неизвестное значение, потому что пара обычно
  настраивается из одного `.env`, и `NET=test` иначе упал бы глубоко внутри
  поиска класса монеты.
- **Контейнер становится healthy только когда начинает обслуживать клиентов** —
  то есть после того, как догнал демона. Первая индексация mainnet занимает
  несколько суток, и всё это время контейнер будет unhealthy; смотрите логи. На
  regtest это секунды.
- **Самоподписанный сертификат создаётся, только если `SERVICES` требует TLS, а
  файлы не заданы.** Клиентам придётся доверять ему явно. Это плата за то, что
  ElectrumX отказывается стартовать при запросе `ssl://` без сертификата — не
  лучший способ узнать, что вы добавили порт.