# Основная платформа

Основная платформа — это операционное ядро Vilna, обеспечивающее мониторинг блокчейна в реальном времени, генерацию кошельков и комплексную аналитику данных. Она служит фундаментом для создания любого крипто-приложения — от простых платежных процессоров до сложных DeFi платформ.

## Назначение и возможности

Основная платформа решает фундаментальные задачи интеграции с блокчейном:

- **Управление кошельками**: Генерация и организация миллионов адресов из одного xPub ключа
- **Мониторинг в реальном времени**: Отслеживание активности блокчейна в нескольких сетях одновременно
- **Доступ к данным**: Мгновенный запрос исторических транзакций и текущих балансов
- **Уведомления о событиях**: Получение оповещений при возникновении определенных событий в блокчейне


## Компоненты архитектуры


```mermaid
graph TB
    subgraph "Входной слой"
        XPUB[xPub ключи]
        ADDR[Отдельные адреса]
        IMPORT[Массовый импорт]
    end
    
    subgraph "Ядро обработки"
        GEN[Генератор адресов]
        MON[Монитор блокчейна]
        INDEX[Индексатор данных]
        CACHE[Кэш балансов]
    end
    
    subgraph "Выходной слой"
        WEBHOOK[Вебхуки]
        API[REST API]
        EMAIL[Email оповещения]
        WS[WebSocket]
    end
    
    XPUB --> GEN
    GEN --> MON
    ADDR --> MON
    IMPORT --> MON
    MON --> INDEX
    INDEX --> CACHE
    INDEX --> WEBHOOK
    CACHE --> API
    INDEX --> EMAIL
    CACHE --> WS
```

## Реальные сценарии использования

### Криптовалютная биржа

Биржи должны управлять миллионами депозитных адресов пользователей, отслеживая все входящие транзакции:


```mermaid
sequenceDiagram
    participant Пользователь
    participant Биржа
    participant Vilna
    participant Блокчейн
    
    Пользователь->>Биржа: Запрос депозитного адреса
    Биржа->>Vilna: Генерация нового адреса
    Vilna->>Биржа: Возврат уникального адреса
    Биржа->>Пользователь: Отображение депозитного адреса
    
    Пользователь->>Блокчейн: Отправка средств
    Блокчейн->>Vilna: Транзакция обнаружена
    Vilna->>Биржа: Webhook уведомление
    Биржа->>Биржа: Зачисление на счет пользователя
```

**Подход к реализации:**

1. Импорт xPub ключа биржи через [`POST /xpubs`](/apis/spec#operation/createXpub)
2. Генерация уникальных адресов для каждого пользователя с [`POST /addresses/generate/xpub/next`](/apis/spec#operation/generateNextAddress)
3. Настройка webhook уведомлений для входящих транзакций
4. Автоматическая обработка депозитов при достижении порога подтверждений


### Платежный шлюз

Платежные процессоры должны создавать уникальные адреса для каждого счета и проверять платежи:

**Ключевые требования:**

- Генерация платежных адресов по требованию
- Мониторинг точных сумм платежей
- Обработка частичных платежей и переплат
- Поддержка множества криптовалют


**Решение с Vilna:**

- Использование API генерации адресов для создания уникальных платежных адресов
- Настройка вебхуков для получения уведомлений о платежах
- Запрос API балансов для проверки сумм платежей
- Отслеживание истории транзакций для сверки


### DeFi портфель-трекер

DeFi платформам необходимо агрегировать позиции пользователей в различных протоколах:

**Требования к мониторингу:**

- Отслеживание балансов кошельков пользователей в разных сетях
- Мониторинг позиций в пулах ликвидности
- Расчет общей стоимости портфеля
- Обнаружение взаимодействий с DeFi протоколами


**Vilna обеспечивает:**

- Массовый импорт пользовательских адресов для мониторинга
- Отслеживание балансов в реальном времени по всем поддерживаемым токенам
- Исторические данные для анализа производительности портфеля
- Уведомления о событиях при изменении позиций


## Основные функциональности

### Генерация адресов

Генерация HD wallet адресов по стандартам BIP32/44/84. Система поддерживает:

- Последовательную генерацию адресов с обработкой лимита пропусков
- Маркировку адресов и хранение метаданных
- Автоматический мониторинг всех сгенерированных адресов
- Поддержку множественных путей деривации


Соответствующие API эндпоинты:

- [`POST /xpubs`](/apis/spec#operation/createXpub) - Импорт xPub ключей
- [`POST /addresses/generate/xpub/next`](/apis/spec#operation/generateNextAddress) - Генерация следующего адреса
- [`GET /addresses`](/apis/spec#operation/getAddresses) - Список всех адресов


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

Движок мониторинга непрерывно сканирует множество блокчейнов на предмет активности отслеживаемых адресов:

**Поддерживаемые сети:**

- EVM сети (Ethereum, BSC, Polygon, Arbitrum, Optimism)
- Bitcoin и Bitcoin-совместимые сети
- Решения второго уровня
- Альтернативные сети (Solana, TON и др.)


**Возможности мониторинга:**

- Обнаружение транзакций (ожидающие и подтвержденные)
- Переводы токенов (ERC-20, BEP-20, SPL)
- Перемещения NFT
- Взаимодействия со смарт-контрактами
- Внутренние транзакции


### Система уведомлений

Настройка оповещений в реальном времени о событиях блокчейна:

**Webhook уведомления:**

- HTTP POST запросы на ваши эндпоинты
- HMAC подпись для безопасности
- Автоматические повторные попытки с экспоненциальной задержкой
- Отслеживание статуса доставки


**Email оповещения:**

- Настраиваемые шаблоны
- Триггеры на основе порогов
- Ежедневные сводные отчеты
- Уведомления о критических событиях


**Типы событий:**

- `transaction.pending` - Обнаружена неподтвержденная транзакция
- `transaction.confirmed` - Транзакция достигла порога подтверждений
- `balance.changed` - Обновлен баланс адреса
- `token.received` - Обнаружен перевод токенов ERC-20/BEP-20


### Аналитика данных

Доступ к комплексным данным блокчейна через API:

**Запросы балансов:**

- Текущий баланс по адресу
- Агрегация балансов множества токенов
- Расчет стоимости в USD
- Снимки истории балансов


**История транзакций:**

- Полные записи транзакций
- Расширенные опции фильтрации
- Детали переводов токенов
- Аналитика использования газа


Соответствующие API эндпоинты:

- [`GET /addresses/{address}/balances`](/apis/spec#operation/getAddressBalances) - Получение текущих балансов
- [`GET /transactions`](/apis/spec#operation/getTransactions) - Запрос истории транзакций


## Паттерны интеграции

### Обработка больших объемов

Для приложений, обрабатывающих тысячи адресов:

1. Используйте массовый импорт для существующих адресов
2. Реализуйте очередь вебхуков для уведомлений большого объема
3. Кэшируйте данные балансов локально с периодическим обновлением
4. Используйте пагинацию для больших запросов данных


### Соображения безопасности

- **Без приватных ключей**: Основная платформа работает только в режиме просмотра
- **HMAC верификация**: Проверяйте все подписи вебхуков
- **Ограничение скорости**: Реализуйте соответствующее ограничение запросов
- **Идемпотентность**: Корректно обрабатывайте дублированные уведомления


### Оптимизация производительности

- **Пакетные операции**: Группируйте множественные запросы когда возможно
- **Фильтрация вебхуков**: Подписывайтесь только на нужные события
- **Локальное кэширование**: Храните часто используемые данные
- **Эффективные запросы**: Используйте соответствующие фильтры и пагинацию


## Сравнение с альтернативами

### vs. Собственная нода

**Преимущества:**

- Не требуется обслуживание инфраструктуры
- Поддержка множества сетей без множественных нод
- Встроенная система уведомлений
- Автоматическое обнаружение токенов


**Когда использовать Vilna:**

- Требуется поддержка множества сетей
- Хотите сосредоточиться на бизнес-логике
- Нужна надежная работоспособность без DevOps накладных расходов


### vs. Другие блокчейн API

**Уникальные возможности:**

- Генерация адресов на основе xPub
- Единый API для всех блокчейнов
- Настраиваемые правила уведомлений
- Надежность корпоративного уровня


## Начало работы

1. **Определите требования**: Определите, какие блокчейны и события вам нужно отслеживать
2. **Импортируйте адреса**: Используйте xPub ключи для новых адресов или массовый импорт существующих
3. **Настройте уведомления**: Настройте вебхуки или email оповещения для соответствующих событий
4. **Интегрируйте API**: Используйте REST API для запросов балансов и транзакций


Для деталей реализации обратитесь к:

- [Быстрый старт](/ru/guides/quickstart) - Пошаговые инструкции по настройке
- [Справочник API](/apis/spec) - Полная документация API
- [Каналы уведомлений](/ru/guides/channels) - Настройка вебхуков и email


## Следующие шаги

- [Обзор архитектуры](/ru/guides/architecture-overview) - Понимание полной платформы
- [Обработка транзакций](/ru/guides/transactions) - Узнайте о создании и подписании транзакций
- [MPC управление ключами](/ru/guides/mpc) - Изучите продвинутые опции безопасности