При создании криптоплатежного шлюза разработчики вскрывают неочевидные проблемы. Реорганизации блокчейна могут отменить транзакции, которые уже считались подтверждёнными. Неправильный выбор модели хранения ключей — и безопасность нарушена. Отсутствие архитектуры коннекторов с circuit breaker оборачивается падением SLA. На практике один клиент потерял $200k из-за реорга — мы учли это в архитектуре. Проектирование до написания кода экономит месяцы переработок, а грамотная документация — основу для масштабирования. За нашими плечами 10+ лет блокчейн-разработки и 50+ реализованных проектов для финтеха. Мы строим шлюзы, которые выдерживают нагрузку до 10 000 транзакций в час. Оценим ваш проект за 1 день — свяжитесь с нами.
Как выбрать между кастодиальной и некастодиальной схемой?
Прежде чем рисовать диаграммы, нужно ответить на вопросы, определяющие всё остальное. Сравним оба подхода:
| Характеристика | Кастодиальная | Некастодиальная |
|---|---|---|
| Контроль над ключами | Шлюз управляет ключами клиентов | Мерчант управляет ключами, шлюз только мониторит |
| Юридическая ответственность | Высокая, требуется лицензия ПД | Низкая, лицензия не обязательна |
| Сложность архитектуры | Максимальная — HSM/KMS, signing service, compliance | Минимальная — только мониторинг блокчейна |
| Скорость запуска | Месяцы (лицензия, аудит) | Недели |
Кастодиальная схема выбирается, если нужен полный контроль над деньгами пользователей и вы готовы к регуляторным требованиям. Некастодиальная — если мерчант хочет сам управлять рисками, а шлюз только обеспечивает подтверждение платежей.
Фундаментальные требования
Выбор сетей определяет инфраструктуру. Bitcoin UTXO-модель несовместима с EVM account-model. TON — своя VM. Каждая сеть добавляет операционную нагрузку.
Модель расчётов: мерчант получает крипту as-is, или шлюз конвертирует в фиат? При конвертации появляется курсовой риск и нужна интеграция с биржей/OTC.
Объём и SLA: 100 транзакций/день и 100 000 — разные архитектуры. SLA 99.9% (8.7 часов downtime/год) и 99.99% (52 минуты/год) — принципиально разные требования к избыточности.
Компонентная архитектура
┌─────────────────────────────────────────────────────────────┐ │ Merchant-facing API │ │ REST / Webhooks / SDK библиотеки │ └───────────────────────┬─────────────────────────────────────┘ │ ┌───────────────────────▼─────────────────────────────────────┐ │ Core Services │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │Invoice Service│ │Address Alloc │ │ Exchange Rate │ │ │ │(create/query) │ │(HD wallet │ │ Service │ │ │ └──────────────┘ │ derivation) │ └──────────────────┘ │ │ └──────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │Confirmation │ │Settlement │ │ Notification │ │ │ │Tracker │ │Service │ │ Service │ │ │ └──────────────┘ └──────────────┘ └──────────────────┘ │ └───────────┬──────────────────────────────────┬──────────────┘ │ │ ┌───────────▼──────────┐ ┌────────────▼──────────────┐ │ Blockchain Layer │ │ Data Layer │ │ │ │ │ │ BTC Connector │ │ PostgreSQL (orders,txns) │ │ EVM Connector │ │ Redis (rates, sessions) │ │ TON Connector │ │ Message Queue (Kafka/RMQ) │ │ TRON Connector │ └────────────────────────────┘ └──────────────────────┘ Core Services: Invoice и Address
Invoice Service управляет конечным автоматом: created → address_assigned → payment_detected → confirming → confirmed → settled | expired | failed. Каждый инвойс хранит exchange_rate_expires_at отдельно от expires_at — это позволяет обновлять курс без пересоздания инвойса.
interface Invoice { id: string; merchant_id: string; external_order_id: string; requested_currency: 'USD' | 'EUR'; requested_amount: Decimal; payment_currency: 'BTC' | 'ETH' | 'USDT_ERC20' | 'USDT_TRC20'; payment_network: 'bitcoin' | 'ethereum' | 'tron'; payment_address: string; payment_amount: Decimal; exchange_rate: Decimal; exchange_rate_expires_at: Date; status: InvoiceStatus; received_amount: Decimal; tx_hash: string | null; confirmations: number; required_confirmations: number; created_at: Date; expires_at: Date; confirmed_at: Date | null; settled_at: Date | null; } Address Allocation использует HD wallet с BIP-44. Pre-generation батчами по 1000 адресов избегает задержек при создании инвойса. Критическое правило: один адрес — один инвойс. Даже если инвойс истёк, адрес не переиспользуется. Подробнее о BIP-44 в спецификации.
CREATE TABLE address_pool ( id BIGSERIAL PRIMARY KEY, network VARCHAR(20) NOT NULL, coin_type INTEGER NOT NULL, address_index BIGINT NOT NULL, address VARCHAR(200) NOT NULL, allocated_at TIMESTAMPTZ, invoice_id UUID REFERENCES invoices(id), UNIQUE(network, address_index) ); Blockchain Connectors: как обеспечить надёжность
Все коннекторы реализуют единый интерфейс. Для EVM-сетей один экземпляр с динамической ротацией RPC-эндпоинтов через circuit breaker — после 3 неудачных попыток переключается на резервный.
interface BlockchainConnector { watchAddress(address: string, callback: (tx: IncomingTransaction) => void): () => void; getTransaction(txHash: string): Promise<TransactionDetail>; getConfirmations(txHash: string, blockNumber: number): Promise<number>; buildSweepTransaction(from: string, to: string, amount: bigint): Promise<UnsignedTx>; broadcastTransaction(signedTx: string): Promise<string>; validateAddress(address: string): boolean; estimateFee(): Promise<bigint>; } EVM-коннектор обрабатывает транзакции в 10 раз быстрее, чем Bitcoin из-за отсутствия UTXO-модели. Для TRON используем tronweb.
Пример настройки коннектора с circuit breaker
При инициализации коннектора передаётся список RPC-эндпоинтов. Для каждого эндпоинта ведётся счётчик ошибок. При превышении порога эндпоинт помечается недоступным на заданный период. Параллельно запускается health-check, который восстанавливает эндпоинт после успешного ответа.
Почему обработка реорганизаций критична для шлюза?
Реорг — блоки, которые вы уже обработали, стали неканоническими. Транзакция, считавшаяся подтверждённой, исчезает. Защита: никогда не помечать инвойс settled при количестве подтверждений меньше безопасного порога.
| Сеть | Безопасные подтверждения | Примерное время |
|---|---|---|
| Bitcoin | 3 (мелкие) / 6 (крупные) | 30-60 мин |
| Ethereum | 12-15 | 3-4 мин |
| Polygon | 128 (до checkpoint) | 5-7 мин |
| Arbitrum | 1 (optimistic, L2) | 15 сек |
| TRON | 20 | 1 мин |
Согласно Bitcoin Wiki, для крупных транзакций рекомендуется 6 подтверждений. Дополнительно: храните block_hash вместе с tx_hash. При каждой проверке подтверждений верифицируйте, что блок с этим хешом всё ещё в canonical chain.
Операции: sweep и webhooks
Sweep — автоматический перевод средств с платёжного адреса на холодный кошелёк. Воркер запускается после каждого подтверждения. Если сумма меньше комиссии — логируем, но не отправляем.
Webhook система — мерчант подписывается на события. Exponential backoff: 30 сек → 5 мин → 30 мин → 2 часа → 24 часа. После 5 неудач — алерт. HMAC-подпись каждого payload для верификации.
interface WebhookDelivery { id: string; merchant_id: string; invoice_id: string; event_type: 'payment.detected' | 'payment.confirmed' | 'payment.settled' | 'payment.expired'; payload: object; status: 'pending' | 'delivered' | 'failed'; attempts: number; next_retry_at: Date; delivered_at: Date | null; } Безопасность
Ключи никогда не хранятся в application-серверах — только HSM или KMS (AWS KMS, HashiCorp Vault). Signing service — изолированный микросервис с минимальными привилегиями. IP whitelist для webhook-эндпоинта мерчанта (опционально). Rate limiting на создание инвойсов: не более 100/мин на мерчанта. Аудит всех действий через append-only таблицу.
Что входит в работу
- Architecture Decision Records по каждому ключевому решению
- OpenAPI спецификация всех API-эндпоинтов
- ER-диаграмма схемы БД
- Диаграммы компонентов и последовательностей
- Документация по развёртыванию и мониторингу
- Доступ к репозиторию с шаблоном коннекторов
- Обучение команды (2 часа воркшоп)
- Поддержка на этапе разработки (2 недели)
Процесс проектирования
- День 1: сбор требований — сети, валюты, объёмы, SLA, модель расчётов, юрисдикция.
- День 2: проектирование схемы данных и core services.
- День 3: blockchain connectors, resilience, реорг-стратегия.
- День 4: API контракты, webhook-события, SDK.
- День 5: security review, threat model, финальная документация.
Результат — полный набор артефактов для разработки. Благодаря продуманной архитектуре заказчики экономят от $20 000 на переделках. Типовой проект окупается за квартал. Получите консультацию по вашему проекту — свяжитесь с нами.