При создании криптоплатежного шлюза разработчики вскрывают неочевидные проблемы. Реорганизации блокчейна могут отменить транзакции, которые уже считались подтверждёнными. Неправильный выбор модели хранения ключей — и безопасность нарушена. Отсутствие архитектуры коннекторов с 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 на переделках. Типовой проект окупается за квартал. Получите консультацию по вашему проекту — свяжитесь с нами.