Проектування архітектури криптоплатіжного шлюзу

При створенні криптоплатіжного шлюзу розробники виявляють неочевидні проблеми. Реорганізації блокчейну можуть скасувати транзакції, які вже вважалися підтвердженими. Неправильний вибір моделі зберігання ключів — і безпеку порушено. Відсутність архітектури конекторів із circuit breaker обертається падінням SLA. На практиці один клієнт втратив $200k через реорг — ми врахували це в архітектурі. Проектування до написання коду економить місяці переробок, а грамотна документація — основу для масштабування. За нашими плечима 10+ років блокчейн-розробки та 50+ реалізованих проєктів для фінтеху. Ми будуємо шлюзи, які витримують навантаження до 10 000 транзакцій на годину. Оцінимо ваш проєкт за 1 день — зв'яжіться з нами.

Як вибрати між кастодіальною та некастодіальною схемою?

Перш ніж малювати діаграми, потрібно відповісти на питання, що визначають усе інше. Порівняємо обидва підходи:

Кастодіальна схема забезпечує в 3 рази більше контролю, але вимагає в 5 разів більше ресурсів на комплаєнс. Вона обирається, якщо потрібен повний контроль над грошима користувачів і ви готові до регуляторних вимог. Некастодіальна — якщо мерчант хоче сам керувати ризиками, а шлюз лише забезпечує підтвердження платежів.

Фундаментальні вимоги

Вибір мереж визначає інфраструктуру. 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 у специфікації 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.

Чому обробка реорганізацій критична для шлюзу?

Реорг — блоки, які ви вже обробили, стали неканонічними. Транзакція, що вважалася підтвердженою, зникає. Захист: ніколи не позначати інвойс settled при кількості підтверджень менше безпечного порогу.

Згідно з 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 таблицю. Гарантуємо безпеку завдяки сертифікованому HSM та регулярному аудиту.

Що входить у роботу

• Architecture Decision Records за кожним ключовим рішенням
• OpenAPI специфікація всіх API-ендпоінтів
• ER-діаграма схеми БД
• Діаграми компонентів та послідовностей
• Документація з розгортання та моніторингу
• Доступ до репозиторію з шаблоном конекторів
• Навчання команди (2 години воркшоп)
• Підтримка на етапі розробки (2 тижні)

Процес проектування

1. День 1: збір вимог — мережі, валюти, обсяги, SLA, модель розрахунків, юрисдикція.
2. День 2: проектування схеми даних та core services.
3. День 3: blockchain connectors, resilience, реорг-стратегія.
4. День 4: API контракти, webhook-події, SDK.
5. День 5: security review, threat model, фінальна документація.

Результат — повний набір артефактів для розробки. Завдяки продуманій архітектурі замовники економлять від $20 000 на переробках. Типовий проєкт коштує $15 000–30 000 та окупається за квартал. Отримайте консультацію щодо вашого проєкту — зв'яжіться з нами.