Escrow: KYC/KYB integration & EXCHANGE_ROLE lifecycle

Title: Escrow: KYC/KYB integration & EXCHANGE_ROLE lifecycle (recovery uses risk signal only) Status: draft Owner: Artur Inspector Date: 2026-01-14

Context:

Mervey — некастодиальный кошелёк + P2P эскроу. Сервер не хранит ключи/сид.
Для escrow мерчанты должны быть проверены (KYC/KYB) и допущены к on-chain ролям (EXCHANGE_ROLE).
Для recovery KYC провайдер должен давать только risk-based сигнал допуска (не ключ/пароль), чтобы не становиться центром доверия.
Нужен санкционный скрининг + гео-ограничения (risk-based, ongoing monitoring).

Decision / Scope:

Backend (основная работа):

Интеграция API KYC-провайдера (Sumsub/Onfido/Veriff/др.)
Хранение статусов: pending | approved | rejected | expired
Webhooks от провайдера → обновление статусов и аудит
Санкционный скрининг (OFAC/EU/UN) + geo блок
Ongoing monitoring (перепроверка при изменениях в списках / risk events)

Blockchain / smart contracts (включая tx-gateway):

Escrow: после KYC_APPROVED для merchant → grantRole(EXCHANGE_ROLE, merchant_address) через multisig/tx-gateway/HSM
Escrow audit: emit MerchantWhitelisted(address indexed merchant, bytes32 kycHash) (без PII; хеш записи/аттестации)
Escrow revocation: при expired/rejected → revokeRole(EXCHANGE_ROLE, merchant_address) (offchain триггер → onchain)
Recovery: KYC = только сигнал допуска перед стартом recovery session (backend ↔ KYC API), не ключ
Events: аудит-события для комплаенса (например KYCCheckPassed, RecoveryInitiated)

Backend ↔ blockchain wiring (целевое):

[Merchant] → [KYC Provider] → [Backend webhook]
                                 ↓
                         [DB status=approved]
                                 ↓
                 [TX Gateway / HSM signer] → [Contract: grantRole]
                                 ↓
                    [Event: MerchantWhitelisted]

Profile / gating (KYC-шнутый или нет?):

Роль	KYC обязателен	Что даёт
Обычный юзер	Нет (non-custodial)	Кошелёк работает без KYC
Recovery	Да (сигнал)	Допуск к recovery session, не ключ
Мерчант (escrow)	Да (KYC/KYB)	`EXCHANGE_ROLE`, доступ к P2P
Высокие лимиты	Возможно	Tier-система, если будет

Consequences:

KYC не ломает базовый non-custodial продукт, но обязателен для мерчантов и risk-gated recovery.
On-chain enforcement делается через роли (EXCHANGE_ROLE), а не через хранение PII в контракте.
У комплаенса появляется auditable trail: webhook logs + on-chain events.

Questions (to backend/product/legal):

Какой провайдер выбран и какие обязательные поля/страны/лимиты?
Какие данные храним локально vs запрашиваем по API (минимизация данных)?
Tier-система лимитов или бинарный допуск?
Частота/триггеры ongoing monitoring?
Нужен ли onchain аудит через kycHash или достаточно событий + offchain хранилища?

Links:

Escrow flow: escrow/flows/flow-exchange.md
Wallet recovery flow: wallet/flows/flow-wallet-recovery-2of3.md
Recovery decision: wallet/decisions/decision-2026-01-13-recovery-2of3.md
Company snapshot: main/company.md

Уточнить провайдера и получить доступ к sandbox API
Согласовать формат MerchantWhitelisted и процесс ревокации роли
Прототипировать tx-gateway → grantRole/revokeRole флоу (HSM signer)
Интеграционные тесты: mock webhook → on-chain роль выставлена/снята

Keyboard shortcuts

Mervey Ecosystem Docs