w33.md

Технический Intro проекта W33

Общее описание

W33 — система криптовалютного эквайринга, состоящая из двух основных компонентов:

• Backend (w33-server): NestJS REST API для обработки криптовалютных транзакций
• Frontend (w33-client): Vue 3 веб-приложение для управления проектами и кошельками

Архитектура Backend (w33-server)

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

• Framework: NestJS 10.x (Node.js)
• База данных: MongoDB (Mongoose ODM)
• Real-time: Socket.io для WebSocket соединений
• Документация: Swagger/OpenAPI
• Блокчейн: Поддержка Ethereum, Tron, Binance Smart Chain, Base
• Библиотеки: ethers.js, tronweb, @ton/core для работы с блокчейнами

Основные модули

1. ProjectModule

• Регистрация и управление проектами
• Генерация API ключей трех типов:
  • OWNER — полный доступ
  • DEV — технический доступ (без изменения настроек)
  • GUEST — только чтение
• Создание основных кошельков проекта для накопления средств

2. WalletModule

• Создание пользовательских кошельков
• Генерация адресов для пополнения (ETH, TRX, BNB, BASE)
• Управление активами кошельков

3. TransactionModule

Обработка транзакций через сервисы:

• ExtractionService: Извлечение транзакций из блокчейнов
• ReceiptionService: Обработка входящих транзакций (пополнения)
• PendingService: Управление транзакциями в статусе pending
• SenderService: Отправка исходящих транзакций (выводы)
• FailLiquidatorService: Обработка failed транзакций
• TaxGrabberService: Сбор комиссий с проектов

Статусы транзакций:

• REQUESTED — запрошено
• TRANSACTION — в процессе
• PENDING — ожидается ответ
• RECEIPTING — ожидается подтверждение
• CONFIRMED — подтверждено
• FAIL — ошибка
• CANCELED — отменено

4. CryptoModule

Работа с блокчейнами:

• EthereumModule: Ethereum, BSC, Base сети
• TronModule: Tron сеть
• BlockModule: Отслеживание блоков
• Поддержка ERC20 токенов через Multicall
• Обработка пропущенных блоков

5. CallbackModule

• Отправка webhook'ов проектам о статусах транзакций
• Валидация callback через secret (SHA256 hash)
• Поддержка IP whitelist

6. ApikeyModule

• Хранение и валидация API ключей
• Типизация доступа по уровням
• Шифрование секретов

7. BalanceModule

• Отслеживание балансов кошельков
• Обновление балансов в реальном времени

8. SocketModule

• WebSocket соединения для real-time обновлений
• Уведомления о транзакциях
• События для фронтенда

9. CheckerModule

• Валидация транзакций
• Проверка балансов
• Мониторинг состояния системы

10. EightLendsModule

• Интеграция с 8Lends протоколом
• Обработка специфичных транзакций

11. InvoiceModule

• Управление инвойсами
• Генерация платежных ссылок

12. ProductModule

• Управление продуктами
• Связь с проектами

Guards и Security

• APIKeyGuard: Проверка наличия API ключа
• ApiKeyTypesGuard: Проверка уровня доступа ключа
• RateLimiterGuard: Ограничение запросов (50 req/sec по умолчанию)

Конфигурация

• Поддержка окружений: testnet, mainnet, gfi
• Настройки через settings.ts:
  • Поддерживаемые монеты и сети
  • Лимиты и комиссии
  • Параметры rate limiting
  • Интервалы сборки комиссий

Поддерживаемые сети и токены

• Ethereum (ETH): ETH, USDT, USDC, SOL, XAUT, WBTC
• Binance Smart Chain (BNB): BNB, USDT, USDC, TRX, ETH, SOL, GFI, DEL, WBTC
• Tron (TRX): TRX, USDT, USDC, BTC, IVFUN
• Base: ETH, USDC, 8LNDS

Архитектура Frontend (w33-client)

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

• Framework: Vue 3 (Composition API)
• UI: Vuetify 3
• State Management: Pinia
• Routing: Vue Router 4
• i18n: vue-i18n (поддержка 13 языков)
• Real-time: Socket.io client
• Build: Vite 4

Структура приложения

Компоненты

• auth/: Компоненты аутентификации
• wallet/: Управление кошельками
• transactions/: Отображение транзакций
• settings/: Настройки проекта
• ui/: Переиспользуемые UI компоненты

Views

• Home: Главная страница
• Dash: Дашборд с статистикой
• Wallets: Управление кошельками
• Settings: Настройки проекта
• Invoice: Управление инвойсами
• API: Документация API
• FAQ: Часто задаваемые вопросы
• Partner: Партнерская программа

Store (Pinia)

• app.ts: Глобальное состояние приложения
• actions.ts: Действия для работы с API
• state.ts: Типы состояний

Локализация

Поддержка языков: ru, en, es, fr, hi, hy, it, ja, ka, ko, tr, uk, zh

Рабочий процесс системы

1. Регистрация проекта

1. Клиент отправляет POST /api/project с параметрами проекта
2. Система генерирует:
   • 3 API ключа (OWNER, DEV, GUEST)
   • Основные кошельки проекта (ETH, TRX, BNB, BASE)
3. Для активации необходимо отправить любую сумму на любой адрес проекта

2. Создание пользовательского кошелька

1. Клиент отправляет POST /api/wallet с API ключом
2. Система генерирует адреса для всех поддерживаемых сетей
3. Возвращается _id кошелька и массив адресов

3. Пополнение кошелька

1. Пользователь отправляет криптовалюту на адрес кошелька
2. ExtractionService отслеживает новые блоки в блокчейнах
3. ReceiptionService обрабатывает входящую транзакцию
4. Система отправляет callback на callbackUrl проекта с:
   • Данными транзакции
   • secret для валидации (SHA256(hash + apiKey))
5. Статус транзакции меняется: PENDING → RECEIPTING → CONFIRMED

4. Вывод средств

1. Клиент отправляет POST /api/transaction/send с параметрами:
   • network: eth/trx/bnb/base
   • symbol: ETH/USDT/USDC и т.д.
   • amount: сумма
   • toAddress: адрес получателя
2. SenderService создает транзакцию и отправляет в блокчейн
3. Статус: REQUESTED → TRANSACTION → PENDING → CONFIRMED
4. Отправляется callback о статусе вывода

5. Callback валидация

Проект должен валидировать callback:

isValid(hash: string, secret: string): boolean {
  const apiKey = process.env.DEV_KEY;
  return secret === crypto.createHash('sha256')
    .update(hash + ':' + apiKey)
    .digest('hex');
}

Особенности реализации

Мониторинг блокчейнов

• Периодическое сканирование новых блоков через ScheduleModule
• Обработка пропущенных блоков через MissedBlock схему
• Использование Multicall для batch запросов балансов

Безопасность

• API ключи с уровнями доступа
• IP whitelist для проектов
• Rate limiting (50 req/sec)
• Валидация callback через secret
• Шифрование приватных ключей

Масштабируемость

• Event-driven архитектура через EventEmitterModule
• WebSocket для real-time обновлений
• Bottleneck для контроля нагрузки на RPC узлы
• Поддержка нескольких окружений (testnet/mainnet/gfi)

Интеграции

• Telegram бот для уведомлений
• Swagger для API документации
• Автогенерация TypeScript SDK из OpenAPI схемы

Развертывание

Backend

cd w33-server
npm install
npm run build
npm run start:prod

Frontend

cd w33-client
npm install
npm run build
npm run preview:ssr  # для SSR
# или
npm run preview      # для SPA

Конфигурация окружения

Backend требует переменные окружения:

• VERSION: testnet/mainnet
• PORT: порт сервера
• DB_URL: MongoDB connection string
• RPC endpoints для блокчейнов
• Приватные ключи для кошельков

Frontend требует:

• API endpoint для backend
• Socket.io endpoint
• Настройки i18n