# DECISIONS.md — журнал решений (ADR) Каждое решение — короткая запись, чтобы потом не гадать, почему всё устроено так. Формат: дата, статус (принято/рассмотрение/заменено), суть, аргументы за/против, результат. --- ## ADR-001 — Используем свой токен на pump.fun (мемкойн Binary Rocket) - **Дата:** 2026-09-09 - **Статус:** принято - **Суть:** выпускаем СВОЙ токен на pump.fun, а не пользуемся чужим. - **За:** бренд/маркетинг, контроль экономики, стимул игрокам, единая валюта ставок. - **Против:** надо эмитировать и следить за курсом; чужой токен дал бы меньше работы. - **Решение:** свой токен. decimals = 6, Token-2022, создание через `create_v2` (по доке pump.fun). ## ADR-002 — Курс живой рыночный (Способ 1) - **Дата:** 2026-09-09 - **Статус:** принято - **Суть:** вне игры баланс — в фантиках, курс берётся с рынка (bonding curve/AMM pump.fun). Ввод = swap SOL→фантики, вывод = swap фантики→SOL. Никакой фикс-привязки/стейблока. - **За:** нативно pump.fun, привычно игроку-трейдеру, технически проще, маркетинг (рост/падение токена). - **Против:** баланс «гуляет» с рынком; определённым аудиториям неудобно. - **Решение:** Способ 1. (Это и диктует, что ставки идут фантиками через контракт.) ## ADR-003 — Ставки идут фантиками через контракт - **Дата:** 2026-09-09 - **Статус:** принято (вытекает из ADR-002) - **Суть:** игрок ставит токен, контракт держит фантики в своём ATA-ваулте и платит фантиками. - **Следствие:** контракт переводится с нативного SOL (lamports) на SPL-токен — это ядро Фазы 1. - **Против:** трогаем хорошо работающий контракт; но без этого сценарий ввода-игры-вывода не работает. ## ADR-004 — Ввод/вывод через pump.fun swap (`POST /agents/swap`) - **Дата:** 2026-09-09 - **Статус:** принято - **Суть:** пополнение = `inputMint: NATIVE_MINT(SOL), outputMint: наш_mint`; вывод = наоборот. Клиент на бэкенде (Ktor `PumpApiClient`) уже готов в `smart-updown-server`. - **За:** возвращает готовую подписанную swap-транзакцию, бэкенд не держит ликвидность. - **Против:** весь ввод/вывод завязан на доступность pump.fun API. ## ADR-05 (идея) — мета-репозиторий для документации и трекинга - **Дата:** 2026-09-09 - **Статус:** принято - **Суть:** создать `pump-game-ops`, где живут карта репозиториев, решения, экономика и список задач. - **За:** единая точка оркестрации, не плаваем по чату. **Против:** риск превратиться во второй трекер. --- ## ADR-005 — Флоу входа/вывода подтверждён (как описал юзер) - **Дата:** 2026-09-09 - **Статус:** принято - **Суть:** человек заходит в игру → видит баланс 0 → кнопка «Пополнить» (одна, без выбора) → swap SOL→фантики → баланс появляется → ставит фантики через контракт (честное списание/начисление по исходу) → при выходе нажимает «Вывести» → swap фантики→SOL, баланс уменьшается. - **За:** точный пользовательский сценарий, подтверждённый владельцем; простая UX-модель. - **Решение:** именно так и работаем — это источник требований для Фазы 1 (контракт на токене) и Фазы 5 (UI). --- ## ADR-006 — Предмет ставки: цена SOL (валюта — фантики) - **Дата:** 2026-09-09 - **Статус:** принято - **Суть:** валютой ставки являются наши фантики (токен Binary Rocket), но ставка делается на **направление цены SOL** (вверх/вниз) — как и в текущей версии игры. Контракт по-прежнему сравнивает entry/exit_price цены SOL. - **Цена SOL сейчас** — случайная заглушка (`RandomPriceSource`). Позже заменяется на реальную (провайдер/оракул). Это отдельная задача, не блокирует Фазу 1 (контракт от способа получения цены не зависит). **→ Обновление 2026-09-11:** реальный источник выбран — см. ADR-007. - **Следствие:** фантики = касса/валюта ввода-вывода; контракт оперирует токеном, но исход считает по цене SOL. Экономика токена (ADR-002 живой курс) не влияет на логику «вверх/вниз». --- ## ADR-007 — Источник цены SOL = upstream-сервис `binance-market` - **Дата:** 2026-09-11 - **Статус:** принято - **Суть:** цена SOL для `PriceSource` берётся из уже работающего в инвест-кластере сервиса `binance-market` (репо `subochev/binance-market`), а не из своей оракуль-логики и не из прямого опроса Binance. Контракт между игрой и сервисом — публичный: - **NATS-подписка** на топик `market.price.solusdt` (предпочтительно, в кластере); либо - **WebSocket** `ws://:8080/ws/price?symbol=solusdt` (fallback / внешние сети). Источник цены внутри `binance-market` — last-trade (`aggTrade.p` с биржи Binance), тики идут на каждой сделке → фактически real-time. - **За:** - Уже работает и развёрнут в кластере `kube` (ns `invest`), chart `binom/binance-market`, последний релиз v10. Не надо поднимать ещё один процесс ради цены. - Есть и NATS, и WS-контракт — обе формы потребления готовы. - Покрытие `solusdt` уже в списке символов; дополнительных подписок не требуется. - Цена приходит в тиках сделок (не сэмплинг раз в N секунд) — лучшее разрешение для сравнения entry/exit в round-based игре. - Общий сервис инвест-кластера, используется не только этой игрой; его судьба — не наша забота. - **Против:** - Один источник (Binance). Если Binance недоступен — игра без цены. Заглушка-fallback на `RandomPriceSource` остаётся как dev-only. - Зависимость по латентности от стороннего сервиса. В кластере это несколько мс, приемлемо. - **Результат:** задачи «TODO Цена SOL: реальный источник» (Фаза 0) и «PriceSource: реальная цена (вместо RandomPriceSource)» (Фаза 2) переводятся в `IN_PROGRESS` со ссылкой на это решение. Никаких новых подписок/оракулов не делаем — только интеграция в релейере (`smart-updown-token`/ `relayer` или `smart-updown-server`). Внешний статус сервиса см. README → «Внешние зависимости». **→ Обновление 2026-09-13: реализовано, см. ADR-008** (NATS-консьюмер в шлюзе, цена ×1e8, раздача фронту по WS). --- ## ADR-008 — Реализация: цена SOL из NATS в шлюзе + раздача фронту по WS - **Дата:** 2026-09-13 - **Статус:** принято, реализовано - **Контекст:** ADR-006 зафиксировал предмет ставки (цена SOL), ADR-007 выбрал источник (`binance-market` через NATS). Оставалось реализовать: сама цена была случайной заглушкой `RandomPriceSource` / `simulated = 100_000_000 + Math.random()`. Исход раунда был случаен, а не рыночен. При этом в контуре уже работает `binance-market` — сборщик сделок с Binance, который публикует каждую цену в NATS (`market.price.`). - **Решение:** игровой шлюз (`smart-updown-token/relayer`) подписывается на NATS (`market.price.solusdt`) и берёт цену оттуда. Заглушка удалена. - **Транспорт:** core NATS `nats://192.168.88.93:4222`, subject `market.price.solusdt`. Режим — **только чтение**; `binance-market` не трогаем. - **Шкала:** строка из NATS переводится в целое ×**1e8** строковым парсером (без float): `"101.89000000"` → `10189000000`. То же юнит-пространство, что у оракульных цен и у прежней заглушки (`100_000_000`), поэтому контракт сравнивает цены корректно. - **Раздача фронту:** шлюз транслирует каждый тик по WebSocket (`/ws`, снаружи `wss://testfront.binom.pw/api/ws`), сообщение — только цена: `{"type":"price","symbol":"solusdt","price":"102.30...","ts":...}`. - **Отсутствие цены:** считается аварийным состоянием и обрабатывается мягко — шлюз стартует без NATS, запрос цены ждёт таймаут, фронт показывает последнее значение и переподключается. Отдельный сценарий деградации — тема для будущего решения. - **За:** исход раунда становится рыночным (entry/exit — реальные цены Binance); переиспользуется уже работающий сборщик, торговый контур не дублируется; шина отделяет источник цены от её потребителей (игра, аналитика, будущие сервисы). - **Против:** появляется зависимость от NATS и от `binance-market`; core NATS не хранит историю (нет JetStream) — при разрыве подписки цена не «догоняется», нужен живой поток. - **Альтернативы:** (а) прямая подписка шлюза на Binance WS — дублирование сборщика, лишние внешние коннекты; (б) оракул on-chain (Pyth/Switchboard) — правильнее для боя, но дороже и требует фидов; (в) заглушка — отклонено как единственный вариант, оставлена возможность (`setPriceOverride`) для тестов. - **Детали и диаграммы:** `docs/PRICE-NATS.md`, `docs/diagrams/price-flow.puml`.