From 198a41c4d6347158e1782bc57c5140f22bfae670 Mon Sep 17 00:00:00 2001
From: oscux <oscux@noreply.localhost>
Date: Fri, 19 Dec 2025 11:52:36 +0000
Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82?=
 =?UTF-8?q?=D1=8C=20README.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5545b0a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,43 @@
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Пользователь (MiniApp + TON Connect)
+    participant FE as Frontend (MiniApp)
+    participant BE as Backend
+    participant TC as toncenter API v3
+    participant SC as Atomic Payment Contract (1 платеж)
+
+    FE->>BE: CreatePayment -> создать платеж в БД (amount)
+    Note over BE: Генерирует transaction_id и сохраняет в БД: service_public_key, service_private_key, transaction_id, expected_ton_amount, valid_until, статус платежа
+    BE-->>FE: PaymentInit(address, stateInit, payload_signed)
+    Note over BE,FE: payload_signed включает: valid_until, - expected_ton_amount, - (опционально) параметры/ограничения\nи подписан service_public_key
+
+    FE->>User: TON Connect запрос на оплату\n(to=address, stateInit, payload)
+    User->>SC: Internal message + value (TON) с stateInit (деплой) и payload
+    SC->>SC: Проверка подписи (service_public_key) Проверка valid_until Проверка expected_ton_amount == value
+    alt Валидация ОК
+        SC->>SC: status = 1 (Paid / Awaiting confirm) запоминает факт платежа (anti-replay)
+        SC-->>User: Успех, транзакция принята
+    else Валидация НЕ ОК
+        SC-->>User: Reject / bounce (неверная сумма/подпись/истек срок)
+    end
+
+    loop Периодический мониторинг активных платежей
+        BE->>BE: Собрать список активных платежей (valid_until не истек)
+        Note over BE: Для каждого платежа вычисляет адрес контракта из service_public_key + transaction_id
+        BE->>TC: getAccounts / getTransactions / getAccountState (batch до ~1000 адресов)
+        TC-->>BE: Статусы/данные по контрактам
+        alt Найден контракт со status=1 и оплатой
+            BE->>BE: Рассчитать распределение: applying_address, applying_ton_amount,\nsystem_fee_address, reserve_amount
+            BE->>SC: External confirm message (подпись backend/service key)
+            SC->>SC: Проверка подписи confirm Проверка status==1 Проверка applying_amount <= paid_amount
+            SC->>SC: Transfer applying_amount -> applying_address
+            SC->>SC: Остаток -> system_fee_address (минус reserve на хранение)
+            SC->>SC: status = 2 (Confirmed / Distributed)
+            BE-->>BE: Пометить платеж зачисленным (можно кредитовать пользователя)
+        else Контракт не оплачен / нет / истек
+            BE-->>BE: Ничего не делать или закрыть платеж по valid_until
+        end
+    end
+
+```
\ No newline at end of file