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

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