Інтероперабельність учасників

(Розділ: Екосистема та Мережа)

1) Що таке інтероперабельність учасників

Інтероперабельність - здатність різних організацій (операторів, студій, PSP, KYC/AML-провайдерів, мостів, афіліатів, аналітики і говернансу) надійно взаємодіяти один з одним через узгоджені протоколи і контракти, зберігаючи безпеку, приватність і відтворюваність бізнес-результатів.

• Швидкість інтеграцій і масштабування (time-to-integration ↓).
• Передбачуваність (стабільні SLO/SLA по критичних потоках).
• Безпека та комплаєнс (мінімально достатні права, аудит).
• Еволюція без поломок (версіонування, backward-сумісність).

2) Рівні інтероперабельності (модель шарів)

1. Транспорт і мережа: HTTP/2/3, gRPC/QUIC, WebSockets, P2P, mTLS.
2. Ідентичності та довіра: org_id, peer_id, X.509/mTLS, підписи, ротація ключів.
3. Події та дані: уніфіковані схеми подій, каталоги активів/мереж, idempotency.
4. Процеси та бізнес-контракти: payout/settlement, атрибуція, ризик-сигнали, реплікація лімітів.
5. Управління/юридичний шар: SLA/SLO, DPA, ліцензії, регламенти говернансу.
6. Спостережуваність і якість: SLI/SLO, логування, трасування, аудит.

Кожен шар має власні контракти, тести і політику сумісності.

3) Принципи дизайну

Contract-first: API/схеми/події формалізуються насамперед реалізації.
Backward-compatible зміни: стратегія «тільки додавання полів» і депрекейт-вікна ≥ 90 днів.
Capability negotiation: учасники обмінюються підтримуваними можливостями і вибирають загальну підмножину.
Ізоляція та PoLP: доступи та ліміти видані «мінімально необхідні».
Ідемпотентність і детермінізм: повтор-безпечні операції, передбачувані правила конфлікту.
Спостереження за замовчуванням: кореляція запитів/подій (trace-id), квитанції, що перевіряються.
Data minimization: відсутність PII в телеметрії/лейблах, псевдонімізація.

4) Capability negotiation (переговори можливостей)

При рукостисканні учасники публікують маніфест можливостей і версій.

yaml participant:
org_id: "ORG:ACME"
versions:
api: "2. 6. 1"
events: "1. 9. 0"
capabilities:
payouts: { create: true, cancel: true, currencies: [USD, EUR, USDC] }
kyc: { level: ["basic","enhanced"], sla_minutes_p95: 15 }
bridge: { proof: ["light","zk"], challenge_supported: true }
telemetry: { qos: ["P0","P1"], traces: true }
limits:
payouts_daily_usd: 1_000_000 rate_limits: { create_per_minute: 500 }

Рушій сумісності зіставляє маніфести сторін і вибирає профіль роботи (наприклад,'payouts:v2`, `events:v1. 9`).

5) Контракти API/подій і схеми

API-контракти: OpenAPI/gRPC IDL, чіткі коди помилок, ідемпотентні ключі ('Idempotency-Key'), обмеження тіл.
Подієва модель: 'deposit.','payout.','bridge.','kyc.','risk.','product.'- зі стабільними полями.
Довідники/каталоги: мережі, активи, методи платежів, версії SDK, регіони/юрисдикції.
Контракти даних (Data Contracts): тестуються в CI, зміни - через governance з timelock.

yaml event:
id: uuid ts: timestamp_utc type: payout. created    payout. finalized    bridge. lock...
src_org: string dst_org: string payload: object trace_id: string idempotency_key: string signature: string # source signature

6) Версіонування та сумісність

Семантичні версії: `MAJOR. MINOR. PATCH`.
Правила: MINOR/PATCH - назад-сумісні; MAJOR - паралельне існування з «перекладинами» (adapters), депрекейт ≥ 90 днів.
Migration playbooks: шаблони міграції для API/подій/каталогів; емулятори старих форматів.

7) Шаблони інтеграцій (патерни)

Request–Reply + Idempotency: безпечні виплати/ліміти/резерви.
Event-Driven: «джерела істини» розсилають зміни; підписники матеріалізують вітрини.
Outbox/Inbox: атомарна публікація подій з БД; ідемпотентний прийом у передплатника.
SAGA (оркестрація/хореографія): узгоджені мульти-доменні операції (наприклад, «popolneniye→igrovoye sobytiye→vyplata»).
Dual-write guard: заборона прямих подвійних записів без outbox.
Replay/Backfill: відновлення після збоїв зі збереженням порядку і фіналізації.

8) Безпека і довіра

mTLS і прив'язка ключів до'org _ id/peer _ id'.
Підписи подій, журнал довіри (хто і що підписав/отримав).
RBAC/ABAC і квоти: права за ролями, ліміти за операціями/обсягом.
Секрет-менеджмент: ротація, заборона «довгоживучих» токенів, короткі скоупи.
PII/приватність: токенізація, регіональна сегрегація даних (EU/ROW), DSR-процеси (видалення/експорт).
Захист від зловживань: velocity-ліміти, анти-фрод сигнали, санкційні перевірки.

9) SLI/SLO і спостережуваність інтероперабельності

• 'p95 Time-to-Acknowledge'( квітування події).
• 'p95 End-to-End'( створення → фіналізація/виконання).
• 'Success Rate'за типами подій/операцій.
• «Schema/Contract Compliance%» (валідні повідомлення).
• «Proof Coverage%» (частка підписаних/прикріплених доказів).
• `Error Budget Burn` по P0/P1.

• P0 (виплати/міст): p95 E2E ≤ 5 хв, Success ≥ 99. 5%, Ack ≤ 2 с.
• P1 (продуктові): Freshness p95 ≤ 3 мин, Compliance ≥ 99. 9%.
• Контракти даних: Drift MTTA ≤ 5 хв, Breaking changes = 0 без MAJOR.

Дашборди: Interop Ops, Contract Health, Latency & Success, Schema Drift, Security & Keys.

10) Матриця сумісності (тест-дизайн)

• Сценарії: payouts, deposits, bridge, risk, product, telemetry.
• Версії: API v2. 6/v2. 5, events v1. 9/v1. 8.
• Мережеві режими: нормальний, деградація, реорги, затримки DA.
• Юрисдикції: EU/UK/TR/LA - різні каталоги і правила.

Автотести: контрактні тести (producer/consumer), idempotency, retry/compensation, schema-linters, навантажувальні профілі.

11) Референс-схеми і каталоги

Каталог можливостей (SQL)

sql
CREATE TABLE capabilities (
org_id TEXT,
cap_name TEXT,
version TEXT,
params JSONB,
PRIMARY KEY (org_id, cap_name)
);

Реєстр контрактів/версій

sql
CREATE TABLE contracts (
name TEXT, kind TEXT,     -- api    events    catalog version TEXT, status TEXT,  -- active    deprecated    retired breaking BOOLEAN DEFAULT FALSE,
effective_from TIMESTAMPTZ,
deprecates_at TIMESTAMPTZ,
PRIMARY KEY (name, version)
);

Моніторинг сумісності

sql
SELECT name, version, 100. 0SUM(CASE WHEN compliant THEN 1 END)/COUNT() AS compliance_pct
FROM contract_checks
WHERE ts >= now() - INTERVAL '7 days'
GROUP BY name, version;

12) Конфігурації (YAML)

Політика версіонування

yaml versioning:
events: { compatibility: "BACKWARD", deprecate_days: 90 }
api:  { parallel_majors: true, support_minors: 2 }

Idempotency і повтори

yaml idempotency:
header: "Idempotency-Key"
ttl_hours: 72 conflict_policy: "prefer-latest-payload-with-signature"

Класи QoS

yaml qos:
P0: { ack_timeout_ms: 2000, retries: 3, backoff_ms: [100,400,800] }
P1: { ack_timeout_ms: 5000, retries: 2 }
P2: { best_effort: true }

13) Операційні регламенти

Щодня: звіт compliance за контрактами/схемами, прострочені ключі, SLO burn.
Щотижня: комітет інтероперабельності (нові можливості, міграції, депрекейти).
Перед релізом: контракт-тести, canary зі «скляними» метриками, відкатні плани.
Інциденти: єдиний статус-канал, шаблони повідомлень партнерам, пост-мортем ≤ 72 год.

14) Playbook інцидентів

A. Schema/Contract Drift

1. Увімкнути «суворий режим» (відсікати невідповідні повідомлення),

2. відкрити інцидент і повідомити джерела,

3. згенерувати diff,

4. випустити адаптер/фікс,

5. пост-мортем і оновлення лінтерів.

B. масові повтори/дубль-повідомлення

1. Перевірити ідемпотентність/ключі,

2. включити дедуп-фільтри,

3. обмежити галасливого продюсера,

4. перерахунок вітрин.

C. Зростання латентності/просадки ack

1. Приоритизувати P0, збільшити консьюмерів,

2. тимчасово знизити P2 sampling,

3. аналіз маршрутів і мережевих вузьких місць.

D. компрометація ключа учасника

1. Revoke, ротація, оновлення довіреного реєстру,

2. перепідписання критичних батчів/сертифікатів,

3. аудит дій, звіт партнерам.

E. Розбіжність каталогів (активи/мережі)

1. Карантин конфліктних повідомлень,

2. відкат каталогу,

3. перерахунок агрегатів,

4. публікація виправлень.

15) Чек-лист впровадження

1. Визначте рівні та контракти (API, події, каталоги, ключі).
2. Запустіть capability negotiation та реєстр версій/можливостей.
3. Увімкніть ідемпотентність, квоти, QoS, підписи та mTLS.
4. Налаштуйте SLI/SLO, дашборди та алерти (Ack, E2E, Compliance).
5. Автоматизуйте контракт-тести і тест-матрицю сумісності.
6. Введіть регламенти депрекейтів і міграцій (MAJOR паралельно).
7. Регулярно переглядайте каталоги/правила приватності та доступів.

16) Глосарій

Capability negotiation - узгодження підтримуваних можливостей і профілю роботи.
Contract-first - проектування інтерфейсів через формальні контракти до реалізації.
Idempotency - повтор-безпека операцій.
Schema/Contract Drift - розбіжність фактичних повідомлень з оголошеними контрактами.
PoLP - принцип мінімально необхідних прав.
Compliance% - частка повідомлень/запитів, що відповідають контракту.

Підсумок: інтероперабельність учасників - це керована система контрактів, версій, можливостей і спостережуваності. Дотримуючись цього фреймворку, екосистема забезпечує швидкі інтеграції, стійкі бізнес-потоки і безпечну еволюцію без поломок - від рівня мережі та ідентичностей до процесів і говернансу.