From 7ebd5a85e601e573d96568787508e18cbad8f191 Mon Sep 17 00:00:00 2001 From: oscux Date: Mon, 20 Oct 2025 08:04:04 +0000 Subject: [PATCH] =?UTF-8?q?=D0=9E=D0=B1=D0=BD=D0=BE=D0=B2=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=201.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 1.md | 324 ++++++++++++++++++++++++++--------------------------------- 1 file changed, 142 insertions(+), 182 deletions(-) diff --git a/1.md b/1.md index af9403a..e616b7b 100644 --- a/1.md +++ b/1.md @@ -1,233 +1,193 @@ +# M8 на TON — техническое задание -## Цель +## 1. Дизайн и UX -Один экран. Депозит USDT и вывод. Баланс USDT/M8, APY, калькулятор. Вывод в любой момент. История. +* Референс: **@wallet**. +* Адаптация под требования и бренд включена в стоимость. +* Структура: -## Роли + * **Экран Главный**: баланс, APY, калькулятор, «Внести/Вывести», история. + * **Экран Рефералы**: уникальная ссылка `/?r=`, описание программы, сводка начислений. -Пользователь. Администратор. +## 2. Пользовательский доступ -## Экран пользователя +* Доступ к функциям и истории после привязки TON-адреса. -* TON Connect. -* Балансы: USDT, M8. APY. -* Калькулятор: сумма USDT, ползунок месяцев. Подпись: «вывод возможен в любой момент», расчёт рекомендательный. -* Кнопки: «Внести», «Вывести». -* История: депозиты, начисления, клеймы, выплаты. -* Реферальная ссылка: `https://token-m8.com/?r=`. +## 3. Депозит -## Ончейн-модель +* Вызов функции в **M8 Jetton Master** с `amountUSDT` и опциональным `refAddr`. +* Перевод USDT в **Treasury**. +* Минт **M8** на адрес пользователя. +* `refAddr` используется бэкендом для расчёта реферальных начислений. -* **M8 Jetton Master (minter)** — точка входа депозита и рефералов: +## 4. Начисления - * При депозите получает `amountUSDT` и `refAddr` от фронтенда. - * Инициирует перевод USDT пользователя в **Treasury**. - * Минтит M8 пользователю. - * Если `refAddr` валиден и не равен адресу пользователя, минтит рефереру **+3%** M8 в той же транзакции. -* **USDT Jetton** — средство ввода/выплат. Передача в Treasury вызывается логикой M8 Master в рамках той же транзакции. -* **M8 Jetton (FT)** — доля вклада. -* **NFT Claim** — право на выплату при выводе. Свободно передаваемый. Сжигается после выплаты. +* APY задаётся в админ-панели. +* Ежедневно в фиксированный час бэкенд записывает начисления за сутки. +* Реферальные начисления: - * При минте NFT в метаданных устанавливается **backend-URL** на JSON. - * Бэкенд генерирует картинку для кошельков с суммой ожидаемой выплаты и параметрами клейма. + * **Тип 1**: фиксированная отложенная выплата по тиру депозита, выплата через N месяцев. + * **Тип 2**: начисления на доход реферала по ставке, начиная с заданного месяца. -## Оффчейн-модель +## 5. Вывод -* Бэкенд Python: FastAPI, PostgreSQL, SQLAlchemy, Celery. -* Индексатор событий USDT/M8/NFT. HMAC вебхуки. Идемпотентность. -* Начисления APY создаются в БД ежедневно. Батч-минт ончейн — 2–3 раза в неделю или по порогу. +* Запрос подписи параметров выплаты на бэкенде. +* Бэкенд считает итоговую сумму с учётом всех неиндексированных начислений и подписывает параметры. +* Развёртывание **смарт-контракта выплаты** с подписью. +* Выплата USDT владельцу контракта и закрытие контракта. +* Опционально: **NFT-интерфейс** для смарт-контракта выплаты (видимость и передача права требования). -## Авторизация админа +## 6. Учёт баланса M8 -* **Только по кошельку через TON Connect.** -* Без 2FA, паролей, SMS и пр. Доступ разрешён списку whitelisted адресов. +* **Вариант A**: ончейн-баланс M8 не синхронизируется; на экране показывается оценочный баланс = ончейн + оффчейн. +* **Вариант B**: периодический доминт M8 на ончейн при достижении порога; при выплате сумма берётся из подписи бэкенда с учётом хвостов. -## Потоки +## 7. Админ-панель -### Депозит через M8 Jetton Master (одна транзакция) +* Просмотр: пользователи, депозиты, начисления (APY, тип 1, тип 2), контракты выплат, выплаты. +* Настройки: APY, реферальные тиры и задержки, ставка и стартовый месяц для типа 2, час ежедневного расчёта. +* Действия: подготовка выплат, закрытие выплат, экспорт. -1. Фронтенд подписывает в кошельке операцию депозита **в M8 Master**: `amountUSDT`, `refAddr?`. -2. M8 Master переводит USDT пользователя в Treasury. -3. M8 Master минтит M8 пользователю. -4. При валидном `refAddr` минтит рефереру **+3%** M8. -5. Индексатор фиксирует события. История обновляется. +## 8. Бэкенд (Python) -### Начисления APY +* FastAPI, PostgreSQL, SQLAlchemy, TonSDK. +* Ежедневный расчёт начислений. +* Индексатор событий. +* Подпись параметров выплат. +* API: -* В админке задаются APY и порог батча. -* Формулы: `daily_simple = APY/365` или `daily_compound = (1+APY)^(1/365)−1`. -* Ежедневно создаются оффчейн «начисления». -* Если сумма **неончиенных** начислений по адресу ≥ порога или наступил день батча, Celery минтит M8 на сумму накопленных начислений и помечает их как on-chain. -* Реферальные связи **не влияют** на APY и не дают доп. процентов. + * `GET /balances?address=` + * `GET /history?address=&cursor=` + * `POST /deposit/quote` + * `POST /payout/prepare` + * `GET /referrals/summary` + * `POST /admin/apy` + * `POST /admin/ref-config` + * `POST /admin/close-payout` + * `POST /events` -### Вывод +## 9. Данные -* Пользователь вводит сумму 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 или использовать генератор по умолчанию. -* Итоговые адреса контрактов и сеть. +* `users(address, referrer)` +* `deposits(tx_hash, address, usdt_amount, ref_addr, at)` +* `accruals_offchain(id, address, kind(APY|REF1|REF2), amount, day, status)` +* `payout_contracts(id, address, amount_signed, signature, created_at, status)` +* `payouts(id, contract_id, to, usdt_amount, tx_hash, at)` +* `audit(id, actor, action, at)` --- -# Mermaid схемы +# Диаграммы (Mermaid) -## UserFlow +## User Flow ```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 + A[Подключить кошелек] --> B[Экран Главный] + B --> C[Внести: вызвать M8 Master с параметрами] + C --> D[USDT перевод в Treasury] + C --> E[Минт M8 на адрес пользователя] + B --> F[Вывести: запрос подписи на бэкенде] + F --> G[Бэкенд возвращает подпись и сумму] + G --> H[Создание контракта выплаты] + H --> I[Выплата USDT и закрытие] + A --> R[Экран Рефералы] + R --> RS[Копирование ссылки и просмотр сводки] ``` -## MoneyFlow +## Money Flow — Вариант A ```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; + U1[USDT у пользователя] --> M8M[M8 Master] + M8M --> TR[Treasury] + M8M --> UM[M8 у пользователя] + BE[Бэкенд] --> DB[База данных] + IDX[Индексатор] --> DB + BE --> PC[Контракты выплат] + UM --> PC ``` -## Accrual Batch +## Money Flow — Вариант B + +```mermaid +flowchart LR + U1[USDT у пользователя] --> M8M[M8 Master] + M8M --> TR[Treasury] + M8M --> UM[M8 у пользователя] + BE[Бэкенд] --> DB[База данных] + IDX[Индексатор] --> DB + BE --> PC[Контракты выплат] + BE --> DM[Доминт при пороге] + DM --> UM + UM --> PC +``` + +## Daily Calc ```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 + participant S as Планировщик + participant BE as Бэкенд + participant DB as База + S->>BE: Запуск расчета за сутки + BE->>DB: Получить пользователей и депозиты + BE->>DB: Добавить начисления APY + BE->>DB: Добавить рефералы тип 2 + BE->>DB: Начислить тип 1 по дате ``` -## Referral Flow +## Payout Contract + +```mermaid +sequenceDiagram + participant D as Приложение + participant BE as Бэкенд + participant PC as Контракт выплаты + D->>BE: Запрос подписи + BE-->>D: Подпись и параметры + D->>PC: Развернуть контракт + PC-->>BE: Событие создан +``` + +## Referral Logic ```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 валиден)"] + X1[Реферер копирует ссылку] --> X2[Реферал открывает ссылку] + X2 --> X3[Привязка адреса] + X3 --> X4[Депозит в M8 Master] + X4 --> X5[Бэкенд фиксирует депозит] + X5 --> X6[Создать запись тип 1] + X5 --> X7[Включить в тип 2] ``` --- -# Коммерческое предложение +# Коммерческие предложения -## Стоимость +## Вариант A — без ончейн-синхронизации балансов -| Блок | Цена | Состав | -| ---------------------------- | --------: | ----------------------------------------------------------------------------------------------------------------- | -| **Смартконтракты 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` в депозит | -| **Поддержка/правки** | **$0** | Инциденты и мелкие правки в рамках текущего функционала | +* Смарт-контракты: **$800** + M8 Jetton Master (депозит, минт пользователю); смарт-контракт выплаты с проверкой подписи. Опционально NFT-интерфейс без доплаты. +* Бэкенд: **$1100** + Ежедневные начисления, рефералы тип 1/2, подпись выплат, индексатор, история, API. +* Фронтенд: **$400** + Экран Главный, экран Рефералы, подключение кошелька, калькулятор, история, депозит с `refAddr`, вывод через подпись. +* Разворачивание: **$200** +* Поддержка и правки 30 дней: **$0** +* Срок: **7 рабочих дней** +* **Итого: $2500** -**Итого: $2 500.** +## Вариант B — с ончейн-синхронизацией балансов -## Сроки - -8 рабочих дней со старта до первой полностью рабочей версии +* Смарт-контракты: **$1200** + M8 Jetton Master, смарт-контракт выплаты, доминт по порогу, события. +* Бэкенд: **$1100** + Начисления, индексатор, доминт при пороге, история, API. +* Фронтенд: **$400** + Экран Главный, экран Рефералы, без индикации ожидания доминта. +* Разворачивание: **$200** +* Поддержка и правки 30 дней: **$0** +* Срок: **14 рабочих дней** +* **Итого: $2800**