outsource-m8-docs/1.md

# M8 на TON — техническое задание

## 1. Дизайн и UX

* Референс: **@wallet**.
* Адаптация под требования и бренд включена в стоимость.
* Структура:

  * **Экран Главный**: баланс, APY, калькулятор, «Внести/Вывести», история.
  * **Экран Рефералы**: уникальная ссылка `/?r=<TON_ADDRESS>`, описание программы, сводка начислений.

## 2. Пользовательский доступ

* Доступ к функциям и истории после привязки TON-адреса.

## 3. Депозит

* Вызов функции в **M8 Jetton Master** с `amountUSDT` и опциональным `refAddr`.
* Перевод USDT в **Treasury**.
* Минт **M8** на адрес пользователя.
* `refAddr` используется бэкендом для расчёта реферальных начислений.

## 4. Начисления

* APY задаётся в админ-панели.
* Ежедневно в фиксированный час бэкенд записывает начисления за сутки.
* Реферальные начисления:

  * **Тип 1**: фиксированная отложенная выплата по тиру депозита, выплата через N месяцев.
  * **Тип 2**: начисления на доход реферала по ставке, начиная с заданного месяца.

## 5. Вывод

* Запрос подписи параметров выплаты на бэкенде.
* Бэкенд считает итоговую сумму с учётом всех неиндексированных начислений и подписывает параметры.
* Развёртывание **смарт-контракта выплаты** с подписью.
* Выплата USDT владельцу контракта и закрытие контракта.
* Опционально: **NFT-интерфейс** для смарт-контракта выплаты (видимость и передача права требования).

## 6. Учёт баланса M8

* **Вариант A**: ончейн-баланс M8 не синхронизируется; на экране показывается оценочный баланс = ончейн + оффчейн.
* **Вариант B**: периодический доминт M8 на ончейн при достижении порога; при выплате сумма берётся из подписи бэкенда с учётом хвостов.

## 7. Админ-панель

* Просмотр: пользователи, депозиты, начисления (APY, тип 1, тип 2), контракты выплат, выплаты.
* Настройки: APY, реферальные тиры и задержки, ставка и стартовый месяц для типа 2, час ежедневного расчёта.
* Действия: подготовка выплат, закрытие выплат, экспорт.

## 8. Бэкенд (Python)

* FastAPI, PostgreSQL, SQLAlchemy, TonSDK.
* Ежедневный расчёт начислений.
* Индексатор событий.
* Подпись параметров выплат.
* API:

  * `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. Данные

* `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)

## User Flow

```mermaid
flowchart TD
  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[Копирование ссылки и просмотр сводки]
```

## Money Flow — Вариант A

```mermaid
flowchart LR
  U1[USDT у пользователя] --> M8M[M8 Master]
  M8M --> TR[Treasury]
  M8M --> UM[M8 у пользователя]
  BE[Бэкенд] --> DB[База данных]
  IDX[Индексатор] --> DB
  BE --> PC[Контракты выплат]
  UM --> PC
```

## 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 Планировщик
  participant BE as Бэкенд
  participant DB as База
  S->>BE: Запуск расчета за сутки
  BE->>DB: Получить пользователей и депозиты
  BE->>DB: Добавить начисления APY
  BE->>DB: Добавить рефералы тип 2
  BE->>DB: Начислить тип 1 по дате
```

## 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
  X1[Реферер копирует ссылку] --> X2[Реферал открывает ссылку]
  X2 --> X3[Привязка адреса]
  X3 --> X4[Депозит в M8 Master]
  X4 --> X5[Бэкенд фиксирует депозит]
  X5 --> X6[Создать запись тип 1]
  X5 --> X7[Включить в тип 2]
```

---

# Коммерческие предложения

## Вариант A — без ончейн-синхронизации балансов

* Смарт-контракты: **$800**
  M8 Jetton Master (депозит, минт пользователю); смарт-контракт выплаты с проверкой подписи. Опционально NFT-интерфейс без доплаты.
* Бэкенд: **$1100**
  Ежедневные начисления, рефералы тип 1/2, подпись выплат, индексатор, история, API.
* Фронтенд: **$400**
  Экран Главный, экран Рефералы, подключение кошелька, калькулятор, история, депозит с `refAddr`, вывод через подпись.
* Разворачивание: **$200**
* Поддержка и правки 30 дней: **$0**
* Срок: **7 рабочих дней**
* **Итого: $2500**

## Вариант B — с ончейн-синхронизацией балансов

* Смарт-контракты: **$1200**
  M8 Jetton Master, смарт-контракт выплаты, доминт по порогу, события.
* Бэкенд: **$1100**
  Начисления, индексатор, доминт при пороге, история, API.
* Фронтенд: **$400**
  Экран Главный, экран Рефералы, без индикации ожидания доминта.
* Разворачивание: **$200**
* Поддержка и правки 30 дней: **$0**
* Срок: **14 рабочих дней**
* **Итого: $2800**