239 lines
11 KiB
Markdown
239 lines
11 KiB
Markdown
Обновлено. Ниже полный MD с правками: админ-авторизация по кошельку; новая стоимость: СК $1300, backend $700, деплой $200, frontend $300; «поддержка/правки 30 дней» объединены и бесплатны.
|
||
|
||
---
|
||
|
||
# M8 на TON — требования продукта (MVP)
|
||
|
||
## Цель
|
||
|
||
Один экран. Депозит USDT и вывод. Баланс USDT/M8, APY, калькулятор. Вывод в любой момент. История.
|
||
|
||
## Роли
|
||
|
||
Пользователь. Администратор.
|
||
|
||
## Экран пользователя
|
||
|
||
* TON Connect.
|
||
* Балансы: USDT, M8. APY.
|
||
* Калькулятор: сумма USDT, ползунок месяцев. Подпись: «вывод возможен в любой момент», расчёт рекомендательный.
|
||
* Кнопки: «Внести», «Вывести».
|
||
* История: депозиты, начисления, клеймы, выплаты.
|
||
* Реферальная ссылка: `https://token-m8.com/?r=<TON_ADDRESS_FULL>`.
|
||
|
||
## Ончейн-модель
|
||
|
||
* **M8 Jetton Master (minter)** — точка входа депозита и рефералов:
|
||
|
||
* При депозите получает `amountUSDT` и `refAddr` от фронтенда.
|
||
* Инициирует перевод USDT пользователя в **Treasury**.
|
||
* Минтит M8 пользователю.
|
||
* Если `refAddr` валиден и не равен адресу пользователя, минтит рефереру **+3%** M8 в той же транзакции.
|
||
* **USDT Jetton** — средство ввода/выплат. Передача в Treasury вызывается логикой M8 Master в рамках той же транзакции.
|
||
* **M8 Jetton (FT)** — доля вклада.
|
||
* **NFT Claim** — право на выплату при выводе. Свободно передаваемый. Сжигается после выплаты.
|
||
|
||
* При минте NFT в метаданных устанавливается **backend-URL** на JSON.
|
||
* Бэкенд генерирует картинку для кошельков с суммой ожидаемой выплаты и параметрами клейма.
|
||
|
||
## Оффчейн-модель
|
||
|
||
* Бэкенд Python: FastAPI, PostgreSQL, SQLAlchemy, Celery.
|
||
* Индексатор событий USDT/M8/NFT. HMAC вебхуки. Идемпотентность.
|
||
* Начисления APY создаются в БД ежедневно. Батч-минт ончейн — 2–3 раза в неделю или по порогу.
|
||
|
||
## Авторизация админа
|
||
|
||
* **Только по кошельку через TON Connect.**
|
||
* Без 2FA, паролей, SMS и пр. Доступ разрешён списку whitelisted адресов.
|
||
|
||
## Потоки
|
||
|
||
### Депозит через M8 Jetton Master (одна транзакция)
|
||
|
||
1. Фронтенд подписывает в кошельке операцию депозита **в M8 Master**: `amountUSDT`, `refAddr?`.
|
||
2. M8 Master переводит USDT пользователя в Treasury.
|
||
3. M8 Master минтит M8 пользователю.
|
||
4. При валидном `refAddr` минтит рефереру **+3%** M8.
|
||
5. Индексатор фиксирует события. История обновляется.
|
||
|
||
### Начисления APY
|
||
|
||
* В админке задаются APY и порог батча.
|
||
* Формулы: `daily_simple = APY/365` или `daily_compound = (1+APY)^(1/365)−1`.
|
||
* Ежедневно создаются оффчейн «начисления».
|
||
* Если сумма **неончиенных** начислений по адресу ≥ порога или наступил день батча, Celery минтит M8 на сумму накопленных начислений и помечает их как on-chain.
|
||
* Реферальные связи **не влияют** на APY и не дают доп. процентов.
|
||
|
||
### Вывод
|
||
|
||
* Пользователь вводит сумму M8. Контракт сжигает M8 и минтит NFT Claim.
|
||
* В метаданных NFT: backend-URL и картинка с суммой ожидаемой выплаты.
|
||
* Админ отправляет USDT владельцу NFT из Treasury.
|
||
* Контракт сжигает NFT Claim. История обновляется.
|
||
|
||
## Реферальная система
|
||
|
||
* Фронтенд формирует ссылку `?r=<адрес реферера>`.
|
||
* При депозите фронтенд передаёт `refAddr` в вызов M8 Master.
|
||
* M8 Master минтит рефереру **+3%** M8 в той же транзакции.
|
||
* Бэкенд ведёт отчётность. Реферальные бонусы не участвуют в APY.
|
||
|
||
## Админ-панель
|
||
|
||
* Просмотр: пользователи, депозиты, начисления, клеймы, выплаты, рефералы.
|
||
* Управление: APY, порог батча, расписание, ручной запуск батча, выплата по клейму, burn NFT.
|
||
* Авторизация: TON Connect, доступ по whitelisted адресам.
|
||
* Аудит и экспорт CSV.
|
||
|
||
## API (кратко, FastAPI)
|
||
|
||
* `GET /balances?address=`
|
||
* `POST /deposit/quote`
|
||
* `POST /withdraw/init`
|
||
* `GET /claims` | `GET /admin/claims`
|
||
* `POST /admin/apy` | `POST /admin/batch/run`
|
||
* `POST /admin/payout`
|
||
* `POST /events` (вебхуки, HMAC)
|
||
|
||
## Данные
|
||
|
||
* Таблицы: users, referrals, deposits, accruals_offchain, accruals_onchain, claims, payouts, audit.
|
||
* Идемпотентность: `tx_hash`, `(date,address)` для APY.
|
||
|
||
## Безопасность
|
||
|
||
* Раздельные ключи: логика депозита/рефералов в M8 Master, выплаты, служебный mint/burn.
|
||
* Хранилище секретов, ограничение доступа к админ-нодам по IP.
|
||
* Валидация `refAddr` на фронтенде и в контракте.
|
||
|
||
## Нефункциональные
|
||
|
||
* p95 API ≤ 300 мс. Доступность 99.9%. Логи, алёрты рассинхронизаций, бэкапы.
|
||
|
||
## Критерии приёмки
|
||
|
||
* Депозит через **M8 Master**: USDT → Treasury, M8 пользователю, +3% рефереру в одной транзакции.
|
||
* APY: оффчейн накопления и батч-минт ≥ порога, 2–3 раза в неделю.
|
||
* Вывод: burn M8 → mint NFT Claim (с backend-метаданными и картинкой) → выплата USDT владельцу → burn NFT.
|
||
* История корректна, расхождений нет.
|
||
|
||
## Открытые вопросы
|
||
|
||
* Значение порога батча и дни запуска.
|
||
* Макет картинки NFT или использовать генератор по умолчанию.
|
||
* Итоговые адреса контрактов и сеть.
|
||
|
||
---
|
||
|
||
# Mermaid схемы
|
||
|
||
## UserFlow
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["TON Connect"] --> B["Единый экран: баланс, APY, калькулятор"]
|
||
B -->|Внести| C["Подписать Депозит в M8 Master (amountUSDT, refAddr)"]
|
||
C --> D["M8 Master переводит USDT пользователя в Treasury"]
|
||
C --> E["M8 Master минтит M8 пользователю"]
|
||
C --> F["Если refAddr валиден → M8 Master минтит +3% рефереру"]
|
||
E --> B
|
||
B -->|Вывести| G["Ввод суммы M8"]
|
||
G --> H["Burn M8 → Mint NFT Claim (метаданные: backend URL, картинка выплаты)"]
|
||
H --> I["Админ отправляет USDT владельцу NFT из Treasury"]
|
||
I --> J["Burn NFT Claim"] --> B
|
||
```
|
||
|
||
## MoneyFlow
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph User
|
||
UUSDT["USDT"]:::t
|
||
UM8["M8"]:::t
|
||
UNFT["NFT Claim"]:::n
|
||
end
|
||
|
||
subgraph TON
|
||
M8M["M8 Jetton Master"]:::sc
|
||
TR["Treasury"]:::sc
|
||
NFTC["NFT Collection"]:::sc
|
||
end
|
||
|
||
subgraph Offchain_Python["Offchain / Python"]
|
||
API["FastAPI"]:::srv
|
||
IDX["Indexer"]:::srv
|
||
CEL["Celery APY"]:::srv
|
||
ADM["Admin UI"]:::srv
|
||
DB["PostgreSQL"]:::db
|
||
IMG["NFT Image Service"]:::srv
|
||
end
|
||
|
||
UUSDT -->|депозит вызовом в M8M| M8M --> TR
|
||
M8M -->|mint| UM8
|
||
M8M -->|mint +3% рефереру| UM8
|
||
|
||
UM8 -->|burn для вывода| NFTC --> UNFT
|
||
ADM -->|выплата USDT владельцу NFT| UUSDT
|
||
ADM -->|burn claim| NFTC
|
||
|
||
NFTC -->|metadata url| IMG
|
||
IDX --> DB
|
||
API <--> DB
|
||
ADM --> API
|
||
CEL --> API
|
||
|
||
classDef t stroke-width:1;
|
||
classDef n stroke-width:1;
|
||
classDef sc stroke-width:1;
|
||
classDef srv stroke-width:1;
|
||
classDef db stroke-width:1;
|
||
```
|
||
|
||
## Accrual Batch
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant S as Scheduler (Celery)
|
||
participant DB as DB
|
||
participant M8 as M8 Master
|
||
S->>DB: Выбрать адреса с суммой offchain-начислений ≥ порога или по расписанию
|
||
loop По каждому адресу
|
||
S->>M8: mint(address, amountAccumulated)
|
||
M8-->>S: ok / tx_hash
|
||
S->>DB: Пометить accruals как onchain_minted
|
||
end
|
||
```
|
||
|
||
## Referral Flow
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
L["Реферер A копирует ссылку ?r=A"] --> V["Реферал B открывает dApp"]
|
||
V --> C["Фронтенд сохраняет refAddr и передаёт его в вызов депозита"]
|
||
C --> D["Пользователь подписывает депозит в M8 Master"]
|
||
D --> E["M8 Master: перевод USDT в Treasury"]
|
||
D --> F["M8 Master: mint M8 пользователю"]
|
||
D --> G["M8 Master: mint +3% M8 рефереру (если refAddr валиден)"]
|
||
```
|
||
|
||
---
|
||
|
||
# Коммерческое предложение
|
||
|
||
## Стоимость
|
||
|
||
| Блок | Цена | Состав |
|
||
| ---------------------------- | --------: | ----------------------------------------------------------------------------------------------------------------- |
|
||
| **Смартконтракты TON** | **$1300** | M8 Jetton Master с логикой депозита и +3% рефералу; NFT Claim с backend-метаданными; скрипты деплоя и верификации |
|
||
| **Backend (Python)** | **$700** | FastAPI, PostgreSQL, Celery APY, индексатор, сервис NFT-изображений, вебхуки, отчёты |
|
||
| **Развёртывание** | **$200** | Docker, Nginx, TLS, логи, базовый мониторинг, бэкапы |
|
||
| **Frontend (1 экран)** | **$300** | TON Connect, калькулятор, история, передача `refAddr` в депозит |
|
||
| **Поддержка/правки 30 дней** | **$0** | Инциденты и мелкие правки в рамках текущего функционала |
|
||
|
||
**Итого: $2 500.**
|
||
|
||
## Сроки
|
||
|
||
7–10 рабочих дней в зависимости от готовности фронтенда.
|