diff --git a/README.md b/README.md index 0562d08..12a83c3 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,22 @@ > - Remote-адреса: `https://git.binom.pw//.git`. > - Ветки: `smart-updown-server` и `fun-game-front2` — `main`; `Smart-game` сейчас на `extract-sources`. +## Внешние зависимости (upstream) + +binance-market — это **не часть игры**, а **общий инфраструктурный сервис инвест-кластера**, +который игра «Бинарная ракета» использует как **upstream-провайдер цены SOL** +(вместо заглушки `RandomPriceSource`, см. ADR-006 → ADR-007). + +| Компонент | Репозиторий | Путь (локально) | Язык/стек | Роль для игры | +|---|---|---|---|---| +| **binance-market** (upstream цены) | `subochev/binance-market` | `~/common-projects/invest/binance-market` | Kotlin / Spring Boot 3.3.5 WebFlux | собирает рыночные данные с Binance (Binance WS: `depth@100ms` + `aggTrade`); выдаёт last-trade через `GET /ws/price?symbol=` (порт 8080) и через NATS-топик `market.price.`; релейер использует это как **`PriceSource`** (см. ADR-007) | + +Контракт между игрой и сервисом: +- **В кластере (предпочтительно):** подписка на NATS-топик `market.price.solusdt` (адрес задаётся + в релейере; прод-адрес см. в его конфиге). +- **Снаружи кластера / тест:** WebSocket `ws://:8080/ws/price?symbol=solusdt`. +- Покрытие символов сейчас: `btcusdt,ethusdt,solusdt` (конфиг `binance.symbols` в values.yaml чарта). + ## Принятые решения (сводка) Ссылка на полный журнал — `docs/DECISIONS.md`. Ключевое: @@ -35,6 +51,7 @@ - **Курс — живой рыночный** (Способ 1): ставки в фантиках, ввод/вывод через swap. - **decimals = 6**, токен через **Token-2022** (по доке pump.fun `create_v2`). - Ставки идут **фантиками через контракт** → контракт переводить с SOL на SPL-токен (это ядро). +- **Цена SOL** — от внешнего upstream `binance-market` (ADR-007), не своя оракуль-логика. Как ходят данные (кто кому что шлёт, включая согласие/подпись игрока) — `docs/FLOW.md` (sequence-диаграммы: текущий localnet-режим без Phantom и целевой боевой с pump.fun+Phantom). @@ -46,6 +63,7 @@ - [ ] Фаза 1 — контракт на токене — **не начато** - [ ] Фаза 4 — задействовать свап-клиент — **клиент готов** - [ ] Фаза 5 — фронт (баланс/пополнение/вывод) — **не начато** +- [ ] Интеграция с `binance-market` (NATS/WS-клиент `PriceSource`) — **см. ADR-007** ## Прочее - Ночная экономика и mint-адреса: `docs/ECONOMY.md` (создаётся в Фазе 0). diff --git a/TASKS.md b/TASKS.md index 03e5da3..aaa977c 100644 --- a/TASKS.md +++ b/TASKS.md @@ -21,14 +21,14 @@ - **Фаза 2 (активная):** релейер перевести с SOL на токен (ops/pda/config). После неё + E2E на localnet. - **Веха «первый щуп»:** 👉 *как только релейер на фантиках + E2E на localnet прогнаны — через `test-front` вы самостоятельно щупаете: пополнить фантики → ставка → результат.* Это первый реальный user-тест (без Unity). -**Параллельные TODO (не блокируют Фазу 2):** реальная цена (вместо RandomPriceSource), эмиссия, ликвидность/комиссии swap. +**Параллельные TODO (не блокируют Фазу 2):** реальная цена (вместо `RandomPriceSource` — источник выбран: `binance-market`, ADR-007, остаётся интеграция), эмиссия, ликвидность/комиссии swap. --- ## Фаза 0 — Экономика и спека (кросс) - [ ] **TODO** ADR-002 зафиксирован, документировать `ECONOMY.md`: токен, курс (Способ 1), decimals=6, mint-адреса — `[pump.meta]` - [x] **DONE** Решить «вверх/вниз» — предмет ставки = цена SOL (ADR-006), валюта = фантики -- [ ] **TODO** Цена SOL: реальный источник вместо `RandomPriceSource` (оракул/провайдер) — не блокирует Фазу 1 +- [ ] **IN_PROGRESS** Цена SOL: реальный источник (ADR-007) — `subochev/binance-market` (NATS `market.price.solusdt` или WS `/ws/price?symbol=solusdt`); остаётся интеграция `PriceSource` в релейере - [ ] **TODO** Кто держит ликвидность swap и комиссии — `[pump.meta]` - [ ] **TODO** Эмиссия: разовая vs постоянная — `[pump.meta]` @@ -43,7 +43,7 @@ ## Фаза 2 — Релейер и цена (АКТИВНАЯ — следующий шаг) - [ ] **IN_PROGRESS** SolanaClient/ops: подписывать/отправлять токеновую ставку (ATA + ваулт) — перевести релейер с SOL на токен - [ ] **TODO** readGlobal: баланс vault_token вместо SOL; ensureVaultFunded — наливать токен в vault -- [ ] **TODO** PriceSource: реальная цена (вместо RandomPriceSource) +- [ ] **IN_PROGRESS** PriceSource: реальная цена (вместо `RandomPriceSource`) — интеграция с `binance-market` (ADR-007); реализация NATS-консьюмера `market.price.solusdt` - [ ] **TODO** Интеграционный тест релейера на токеновом флоу ## Фаза 4 — Бэкенд: задействовать swap @@ -60,7 +60,7 @@ - [x] **DONE** Каркас: Phantom, балансы (фантики+SOL), swap пополнение/вывод через `/api/pump/swap` - [x] **DONE** Ставка вверх/вниз через контракт с поллингом до SETTLED - [ ] **TODO** Перевести подпись под токеновую версию контракта (после Фазы 1) -- [ ] **TODO** Реальный провайдер цены вместо RandomPriceSource (за нами) +- [ ] **TODO** Реальный провайдер цены вместо RandomPriceSource (за нами) → `binance-market` (ADR-007) - [ ] **TODO** Развернуть / дать постоянный URL (nginx/podman) — удобно открывать ## Фаза 6 — E2E и деплой diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 9731e72..7b674ef 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -64,5 +64,36 @@ сравнивает entry/exit_price цены SOL. - **Цена SOL сейчас** — случайная заглушка (`RandomPriceSource`). Позже заменяется на реальную (провайдер/оракул). Это отдельная задача, не блокирует Фазу 1 (контракт от способа получения цены не зависит). + **→ Обновление 2026-09-11:** реальный источник выбран — см. ADR-007. - **Следствие:** фантики = касса/валюта ввода-вывода; контракт оперирует токеном, но исход считает - по цене SOL. Экономика токена (ADR-002 живой курс) не влияет на логику «вверх/вниз». \ No newline at end of file + по цене 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 → «Внешние зависимости». \ No newline at end of file diff --git a/docs/ECONOMY.md b/docs/ECONOMY.md index 501d111..19863db 100644 --- a/docs/ECONOMY.md +++ b/docs/ECONOMY.md @@ -21,7 +21,10 @@ ## Курс и балансы - **Валюта ставки:** наши фантики (токен Binary Rocket). -- **Предмет ставки:** направление цены SOL (вверх/вниз) — ADR-006. Сейчас цена SOL — случайная заглушка, позже — реальная. +- **Предмет ставки:** направление цены SOL (вверх/вниз) — ADR-006. **Источник реальной цены SOL** + — upstream-сервис `binance-market` (см. ADR-007 и README → «Внешние зависимости»). Потребление: + NATS-топик `market.price.solusdt` (предпочтительно) или WS `ws://:8080/ws/price?symbol=solusdt`. + В dev/test допускается оставить `RandomPriceSource`-заглушку. - **Курс:** живой рыночный (ADR-002). Ввод/вывод через swap pump.fun; баланс игрока — в фантиках. - **Фантик = 1 токен-единица/10^6.** - **Баланс игрока:** в ATA (Associated Token Account) на mint; читается `getTokenAccountBalance`.