При створенні криптоплатіжного шлюзу розробники виявляють неочевидні проблеми. Реорганізації блокчейну можуть скасувати транзакції, які вже вважалися підтвердженими. Неправильний вибір моделі зберігання ключів — і безпеку порушено. Відсутність архітектури конекторів із circuit breaker обертається падінням SLA. На практиці один клієнт втратив $200k через реорг — ми врахували це в архітектурі. Проектування до написання коду економить місяці переробок, а грамотна документація — основу для масштабування. За нашими плечима 10+ років блокчейн-розробки та 50+ реалізованих проєктів для фінтеху. Ми будуємо шлюзи, які витримують навантаження до 10 000 транзакцій на годину. Оцінимо ваш проєкт за 1 день — зв'яжіться з нами.
Як вибрати між кастодіальною та некастодіальною схемою?
Перш ніж малювати діаграми, потрібно відповісти на питання, що визначають усе інше. Порівняємо обидва підходи:
| Характеристика | Кастодіальна | Некастодіальна |
|---|---|---|
| Контроль над ключами | Шлюз керує ключами клієнтів | Мерчант керує ключами, шлюз лише моніторить |
| Юридична відповідальність | Висока, потрібна ліцензія ПД | Низька, ліцензія не обов'язкова |
| Складність архітектури | Максимальна — HSM/KMS, signing service, compliance | Мінімальна — лише моніторинг блокчейну |
| Швидкість запуску | Місяці (ліцензія, аудит) | Тижні |
Кастодіальна схема забезпечує в 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.
Приклад налаштування конектора з 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 таблицю. Гарантуємо безпеку завдяки сертифікованому HSM та регулярному аудиту.
Що входить у роботу
- 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 на переробках. Типовий проєкт коштує $15 000–30 000 та окупається за квартал. Отримайте консультацію щодо вашого проєкту — зв'яжіться з нами.