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

(Раздел: Экосистема и Сеть)

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 (оркестрация/хореография): согласованные мульти-доменные операции (например, «пополнение→игровое событие→выплата»).
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% — доля сообщений/запросов, соответствующих контракту.

Итог: интероперабельность участников — это управляемая система контрактов, версий, возможностей и наблюдаемости. Следуя этому фреймворку, экосистема обеспечивает быстрые интеграции, устойчивые бизнес-потоки и безопасную эволюцию без поломок — от уровня сети и идентичностей до процессов и говернанса.