ADR: Интеграция с CryptoBilling (crypto2b.com) для обработки криптоплатежей¶

Статус: В разработке Дата создания: 2025-11-13 Автор: Claude Code Agent Уровень важности: HIGH

Контекст и проблема¶

Saga требует интеграции с внешним провайдером для обработки криптовалютных платежей (депозиты/выводы). Необходимо выбрать архитектурное решение для интеграции с CryptoBilling API (crypto2b.com), который поддерживает 15+ криптовалют и предоставляет REST API для обработки платежей.

Name: Dev Public key part: 70e1f787453a4d2290aa47fde0815bf4 Private: f+4WG3DP0ZjgKCFvwz7hVTmtLuYfgU+MdP4nWUn+4YP9Tu/8cYegagpOGqzkVJRAyvpkzE2nZL3I8uRQtbEN0g==

Анализ требований¶

Функциональные требования¶

Обработка депозитов криптовалют (BTC, ETH, USDT, USDC, и др.)
Выполнение выводов средств
Отслеживание статусов транзакций
Валидация лимитов и проверка рисков
Уведомления о изменении статусов операций
Поддержка различных блокчейн-сетей

Нефункциональные требования¶

Rate Limit: 10 rps (API ограничение)
Безопасность: API-key аутентификация
Надёжность: Идемпотентная обработка callbacks
Мониторинг: Логирование всех операций
Соответствие CLAUDE.md: Canonical implementation, error logging

Технический анализ CryptoBilling API¶

API Спецификации¶

Базовый URL: https://api.cryptobilling.com
Протокол: HTTPS/REST
Формат: JSON
Rate Limit: 10 rps
Аутентификация: API-key based
Формат времени: UTC ISO8601 (yyyy-MM-ddTHH:mm:ssZ)

Основные Endpoints¶

Health - /health - проверка статуса API
Instruments - /instruments/list - список криптовалют и лимитов
Channels - /channels/take - получение адресов депозитов
Deposits - /deposits/list, /deposits/{id} - управление депозитами
Withdrawals - /withdrawals/list - обработка выводов
Service Operations - история комиссионных транзакций

Workflow процессов¶

Deposit Flow:

sequenceDiagram
    participant U as User
    participant S as Saga
    participant C as CryptoBilling
    participant B as Blockchain

    U->>S: Запрос депозитного адреса
    S->>C: POST /channels/take
    C->>S: {address, tag?, expires}
    S->>U: Адрес для депозита
    U->>B: Отправка криптовалюты
    B->>C: Транзакция в блокчейне
    C->>S: Callback/Webhook уведомление
    S->>S: Обновление баланса пользователя

Withdrawal Flow:

sequenceDiagram
    participant U as User
    participant S as Saga
    participant C as CryptoBilling
    participant B as Blockchain

    U->>S: Запрос на вывод
    S->>S: Списание с баланса
    S->>C: POST /withdrawals
    C->>C: Проверка рисков
    C->>B: Отправка транзакции
    C->>S: Callback о статусе
    S->>U: Уведомление о выводе

Архитектурное решение¶

1. Структура модулей¶

backend/
├── services/
│   └── crypto2b/
│       ├── client.go           # HTTP клиент с rate limiting
│       ├── config.go           # Конфигурация из unified config
│       ├── types.go            # Типы запросов/ответов
│       ├── deposits.go         # Логика депозитов
│       ├── withdrawals.go      # Логика выводов
│       ├── callbacks.go        # Обработка webhooks
│       └── monitoring.go       # Метрики и логирование
├── handlers/
│   └── api/
│       ├── crypto2b_deposits.go    # API endpoints депозитов
│       ├── crypto2b_withdrawals.go # API endpoints выводов
│       └── crypto2b_callbacks.go   # Webhook endpoints
└── models/
    ├── crypto2b_transaction.go # Модели для БД
    └── crypto2b_instrument.go  # Модели криптовалют

2. Интеграционная архитектура¶

HTTP Client Layer: - Canonical HTTP клиент с retry logic (экспоненциальный backoff) - Rate limiting (9 rps с буфером для безопасности) - Timeout настройки из unified config - Структурированное логирование всех запросов/ответов

Service Layer: - Crypto2BService - основной сервис с dependency injection - DepositService - обработка депозитов с валидацией - WithdrawalService - обработка выводов с проверками - CallbackService - идемпотентная обработка webhooks

Data Layer: - Новые таблицы: crypto2b_transactions, crypto2b_instruments - Связь с существующими transactions, users - Индексы для быстрого поиска по external_id

3. Безопасность и валидация¶

Аутентификация: - API ключи из unified config (external_services.crypto2b.api_keys.dev) - Rotation strategy для production ключей - Secure storage в environment variables

Валидация: - Проверка лимитов через /instruments/list - Валидация адресов получателей - Проверка балансов перед выводом - Rate limiting на стороне Saga (защита от spam)

Идемпотентность: - Уникальные идентификаторы операций (UUID) - Защита от duplicate callbacks через transaction_id tracking - Retry logic с экспоненциальным backoff

4. Мониторинг и обработка ошибок¶

Логирование (CLAUDE.md compliance):

// Canonical logging обязательно для всех операций
logger.InfoCtx(ctx, "crypto2b_deposit_initiated",
    "user_id", userID,
    "amount", amount.String(),
    "currency", currency,
    "crypto2b_channel_id", channelID,
)

// ОБЯЗАТЕЛЬНОЕ логирование ошибок
logger.ErrorCtx(ctx, "crypto2b_api_error",
    "endpoint", "/deposits",
    "error", err.Error(),
    "response_code", response.StatusCode,
)

Метрики: - Количество успешных/неуспешных операций - Время ответа API crypto2b - Rate limit violations - Callback processing time

Circuit Breaker: - Автоматическое отключение при высокой частоте ошибок - Fallback механизмы для критичных операций - Health check endpoints

5. Конфигурация¶

Используем существующую unified config архитектуру:

# config/integrations.yaml (уже создан)
external_services:
  crypto2b:
    enabled: true
    base_url: "https://api.cryptobilling.com"
    api_version: "v1"

    api_keys:
      dev:
        name: "Dev"
        public_key: "${CRYPTO2B_DEV_PUBLIC_KEY}"
        private_key: "${CRYPTO2B_DEV_PRIVATE_KEY}"
        enabled: true

    security:
      timeout_seconds: 30
      max_retries: 3
      rate_limit_enabled: true
      rate_limit_requests: 9  # Под лимитом API (10 rps)
      rate_limit_window: 1    # 1 секунда

    callbacks:
      base_url: "${CRYPTO2B_CALLBACK_BASE_URL}"  # Наш URL для webhooks
      secret_token: "${CRYPTO2B_CALLBACK_SECRET}" # Для валидации

6. Database Schema¶

-- Инструменты (криптовалюты)
CREATE TABLE crypto2b_instruments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    currency VARCHAR(10) NOT NULL UNIQUE,
    network VARCHAR(50) NOT NULL,
    min_amount DECIMAL(36,18) NOT NULL,
    max_amount DECIMAL(36,18) NOT NULL,
    fee_fixed DECIMAL(36,18) DEFAULT 0,
    fee_percent DECIMAL(8,4) DEFAULT 0,
    confirmations_required INT DEFAULT 1,
    enabled BOOLEAN DEFAULT true,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Транзакции crypto2b
CREATE TABLE crypto2b_transactions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),

    -- Связь с нашими транзакциями
    saga_transaction_id UUID REFERENCES transactions(id),

    -- Данные crypto2b
    crypto2b_id VARCHAR(255) UNIQUE, -- ID от crypto2b
    operation_type VARCHAR(20) NOT NULL, -- 'deposit' | 'withdrawal'
    status VARCHAR(50) NOT NULL, -- 'pending' | 'confirmed' | 'failed'

    -- Финансовые данные
    amount DECIMAL(36,18) NOT NULL,
    currency VARCHAR(10) NOT NULL,
    network VARCHAR(50),

    -- Адреса и детали
    address TEXT,
    tag TEXT, -- Для XRP, EOS и др.
    txhash TEXT, -- Hash транзакции в блокчейне

    -- Комиссии
    fee_amount DECIMAL(36,18) DEFAULT 0,
    fee_currency VARCHAR(10),

    -- Техническая информация
    external_data JSONB, -- Полный ответ от API
    retry_count INT DEFAULT 0,
    last_callback_at TIMESTAMPTZ,

    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Индексы для производительности
CREATE INDEX idx_crypto2b_transactions_user_id ON crypto2b_transactions(user_id);
CREATE INDEX idx_crypto2b_transactions_crypto2b_id ON crypto2b_transactions(crypto2b_id);
CREATE INDEX idx_crypto2b_transactions_status ON crypto2b_transactions(status);
CREATE INDEX idx_crypto2b_transactions_created_at ON crypto2b_transactions(created_at);

Альтернативы рассмотренные¶

1. Прямая интеграция с блокчейн-нодами¶

Плюсы: Полный контроль, нет комиссий посредникам Минусы: Сложность поддержки 15+ блокчейнов, необходимость собственной инфраструктуры мониторинга Решение: Отклонено из-за высокой сложности

2. Другие провайдеры (Coinbase Commerce, BitPay)¶

Плюсы: Альтернативные решения Минусы: Нет готовых API ключей, необходима новая регистрация Решение: Отклонено, так как crypto2b уже настроен

3. Синхронная обработка без callbacks¶

Плюсы: Простая реализация Минусы: Неэффективный polling, высокая нагрузка на API Решение: Отклонено, выбрана асинхронная модель с callbacks

Последствия решения¶

Положительные¶

Быстрая интеграция: API ключи уже получены
Масштабируемость: Поддержка 15+ криптовалют из коробки
Надёжность: Проверенная система обработки платежей
Соответствие CLAUDE.md: Canonical implementation, proper error handling

Риски и митигация¶

Rate Limiting (10 rps): Митигация через queue и batch processing
Зависимость от внешнего API: Мониторинг, circuit breakers, fallbacks
Callback delivery: Идемпотентность, retry mechanisms
Security: Secure key storage, callback validation

Технический долг¶

Необходимость поддержки совместимости с существующей системой транзакций
Миграция данных при смене провайдера в будущем
Возможное дублирование логики валидации между Saga и CryptoBilling

План реализации¶

Этап 1: Foundation (1-2 дня)¶

Создание базовых типов и структур
HTTP клиент с rate limiting
Базовая конфигурация и тесты

Этап 2: Core API Integration (2-3 дня)¶

Реализация Instruments API (получение списка криптовалют)
Реализация Channels API (генерация депозитных адресов)
Базовые unit тесты

Этап 3: Deposits Flow (3-4 дня)¶

Создание депозитных адресов
Обработка callbacks депозитов
Интеграция с существующей системой транзакций
Integration тесты

Этап 4: Withdrawals Flow (3-4 дня)¶

API для инициации выводов
Валидация балансов и лимитов
Обработка callbacks выводов
End-to-end тесты

Этап 5: Monitoring & Production (2-3 дня)¶

Метрики и мониторинг
Error handling и retry logic
Security audit
Deployment и smoke тесты

Общая оценка: 11-16 дней разработки

Критерии принятия решения¶

✅ Техническая совместимость - REST API совместим с Saga архитектурой
✅ Безопасность - API-key аутентификация, HTTPS, валидация callbacks
✅ Производительность - 10 rps достаточно для MVP
✅ Поддержка криптовалют - 15+ валют покрывают потребности
✅ Документация - достаточная для интеграции
✅ Готовность - API ключи уже получены

Заключение¶

Интеграция с CryptoBilling (crypto2b.com) является оптимальным архитектурным решением для обработки криптоплатежей в Saga. Решение обеспечивает необходимую функциональность при соблюдении принципов CLAUDE.md и архитектурных стандартов проекта.

Статус: Готов к реализации Следующие шаги: Создание epic задач для каждого этапа реализации

ADR создан в соответствии с архитектурными принципами Saga и требованиями CLAUDE.md