База данных¶

Exchange Engine использует PostgreSQL в качестве основной СУБД. В схеме определены 28 таблиц, логически разбитых на пять групп: Core (аккаунты и балансы), Trading (торговля), Blockchain (блокчейн), Admin (администрирование), Config (конфигурация).

ER-диаграмма (основные связи)¶

erDiagram
    accounts {
        uuid id PK
        uuid master_account_id FK
        uuid tier_id FK
        string status
        string email
        timestamp created_at
    }
    tiers {
        uuid id PK
        string name
        jsonb limits
    }
    default_tier {
        uuid tier_id FK
    }
    balance_accounts {
        uuid id PK
        uuid account_id FK
        string type
    }
    balances {
        uuid balance_account_id FK
        string asset FK
        numeric available
        numeric locked
    }
    api_keys {
        uuid id PK
        uuid account_id FK
        string key_hash
        string[] permissions
        timestamp created_at
    }
    wallets {
        uuid id PK
        uuid account_id FK
        uuid balance_account_id FK
        string blockchain
        string address
    }
    assets {
        string code PK
        string name
        int8 decimals
        bool active
    }
    asset_networks {
        uuid id PK
        string asset FK
        string network
        bool deposit_enabled
        bool withdraw_enabled
    }
    tickers {
        string symbol PK
        string base_asset FK
        string quote_asset FK
        bool active
    }
    orders {
        uuid id PK
        uuid account_id FK
        uuid balance_account_id FK
        string ticker FK
        string side
        string type
        numeric price
        numeric qty
        numeric filled_qty
        string status
        timestamp created_at
    }
    trades {
        uuid id PK
        uuid buyer_account_id FK
        uuid seller_account_id FK
        string ticker
        numeric price
        numeric qty
        timestamp executed_at
    }
    candles {
        string ticker FK
        string interval
        timestamp open_time
        numeric open
        numeric high
        numeric low
        numeric close
        numeric volume
    }
    book_snapshots {
        uuid id PK
        string ticker FK
        jsonb bids
        jsonb asks
        timestamp created_at
    }
    chain_topups {
        uuid id PK
        uuid wallet_id FK
        string tx_hash
        string asset
        numeric amount
        string status
        timestamp detected_at
    }
    chain_topup_status_history {
        uuid id PK
        uuid chain_topup_id FK
        string status
        timestamp changed_at
    }
    chain_topup_aml_categories {
        uuid chain_topup_id FK
        string category
        numeric score
    }
    topupscan_states {
        string blockchain PK
        int8 last_scanned_block
    }
    bitcoin_utxo {
        string tx_hash PK
        int4 vout PK
        uuid wallet_id FK
        numeric amount
        bool spent
    }
    txes {
        uuid id PK
        uuid tx_batch_id FK
        string blockchain
        string tx_hash
        string status
        numeric amount
        string to_address
    }
    tx_batches {
        uuid id PK
        string blockchain
        string status
        timestamp created_at
    }
    admin_manual_topup {
        uuid id PK
        uuid account_id FK
        string asset
        numeric amount
        string reason
        timestamp created_at
    }
    admin_manual_withdraw {
        uuid id PK
        uuid account_id FK
        string asset
        numeric amount
        string reason
        timestamp created_at
    }
    admin_transfers {
        uuid id PK
        uuid from_account_id FK
        uuid to_account_id FK
        string asset
        numeric amount
        timestamp created_at
    }
    alerts {
        uuid id PK
        string type
        string severity
        jsonb payload
        string status
        timestamp created_at
        timestamp resolved_at
    }
    risk_categories {
        string code PK
        string description
        string action
    }
    blacklist {
        string address PK
        string blockchain
        string reason
        timestamp added_at
    }
    withdraw_settings {
        string asset PK
        string network PK
        numeric min_amount
        numeric max_amount
        numeric fee
        bool enabled
    }

    accounts ||--o{ accounts : "master_account_id (subaccount)"
    accounts }o--|| tiers : "tier_id"
    accounts ||--o{ balance_accounts : "account_id"
    accounts ||--o{ api_keys : "account_id"
    accounts ||--o{ wallets : "account_id"
    balance_accounts ||--o{ balances : "balance_account_id"
    balance_accounts ||--o{ wallets : "balance_account_id"
    wallets ||--o{ chain_topups : "wallet_id"
    chain_topups ||--o{ chain_topup_status_history : "chain_topup_id"
    chain_topups ||--o{ chain_topup_aml_categories : "chain_topup_id"
    wallets ||--o{ bitcoin_utxo : "wallet_id"
    accounts ||--o{ orders : "account_id"
    balance_accounts ||--o{ orders : "balance_account_id"
    accounts ||--o{ trades : "buyer_account_id"
    accounts ||--o{ trades : "seller_account_id"
    tx_batches ||--o{ txes : "tx_batch_id"
    tiers ||--o| default_tier : "tier_id"
    assets ||--o{ asset_networks : "asset"
    assets ||--o{ tickers : "base_asset"
    assets ||--o{ tickers : "quote_asset"

Группа: Core — аккаунты, балансы, тарифы¶

`accounts`¶

Главная таблица пользователей биржи.

Колонка	Тип	Описание
`id`	`uuid` PK	Уникальный идентификатор аккаунта
`master_account_id`	`uuid` FK → `accounts.id`	Ссылка на родительский аккаунт (для субаккаунтов)
`tier_id`	`uuid` FK → `tiers.id`	Тарифный уровень пользователя
`email`	`text`	Email пользователя
`password_hash`	`text`	Хэш пароля
`status`	`text`	Статус: `active`, `restricted`, `blocked`
`created_at`	`timestamptz`	Дата регистрации

Субаккаунты реализованы через самоссылку: master_account_id указывает на родительский аккаунт.

`balance_accounts`¶

Разделяет балансы пользователя по типу: funding (основной кошелёк) и trading (торговый).

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор балансового аккаунта
`account_id`	`uuid` FK → `accounts.id`	Владелец
`type`	`text`	`funding` или `trading`

`balances`¶

Хранит фактические остатки. Составной первичный ключ: (balance_account_id, asset).

Колонка	Тип	Описание
`balance_account_id`	`uuid` FK → `balance_accounts.id`	Балансовый аккаунт
`asset`	`text` FK → `assets.code`	Код актива (например, `BTC`, `USDT`)
`available`	`numeric`	Доступный остаток
`locked`	`numeric`	Заблокировано в ордерах

`api_keys`¶

Ключи API для алгоритмической торговли с HMAC-SHA256 подписью.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор ключа
`account_id`	`uuid` FK → `accounts.id`	Владелец
`key_hash`	`text`	Хэш публичного ключа
`secret_hash`	`text`	Хэш секрета
`permissions`	`text[]`	Список разрешений (`trade`, `withdraw`, …)
`created_at`	`timestamptz`	Дата создания

`tiers`¶

Тарифные уровни с лимитами торговли и комиссиями.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор тарифа
`name`	`text`	Название уровня
`limits`	`jsonb`	Лимиты (суточный объём, комиссии и т.д.)

`default_tier`¶

Одностроковая таблица, указывающая тариф по умолчанию для новых аккаунтов.

Колонка	Тип	Описание
`tier_id`	`uuid` FK → `tiers.id`	Тариф по умолчанию

Группа: Trading — торговля¶

`orders`¶

Ордера пользователей (открытые и исторические).

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор ордера
`account_id`	`uuid` FK → `accounts.id`	Владелец
`balance_account_id`	`uuid` FK → `balance_accounts.id`	Торговый баланс
`ticker`	`text` FK → `tickers.symbol`	Торговая пара
`side`	`text`	`buy` или `sell`
`type`	`text`	`limit`, `market` и т.д.
`price`	`numeric`	Цена (для лимитных ордеров)
`qty`	`numeric`	Объём
`filled_qty`	`numeric`	Исполненный объём
`status`	`text`	`open`, `filled`, `cancelled`, `partial`
`created_at`	`timestamptz`	Время создания

`trades`¶

Исполненные сделки.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор сделки
`buyer_account_id`	`uuid` FK → `accounts.id`	Покупатель
`seller_account_id`	`uuid` FK → `accounts.id`	Продавец
`ticker`	`text`	Торговая пара
`price`	`numeric`	Цена сделки
`qty`	`numeric`	Объём
`executed_at`	`timestamptz`	Время исполнения

`candles`¶

OHLCV-данные для графиков. Составной ключ: (ticker, interval, open_time).

Колонка	Тип	Описание
`ticker`	`text` FK → `tickers.symbol`	Торговая пара
`interval`	`text`	Таймфрейм: `1m`, `5m`, `1h`, `1d` и т.д.
`open_time`	`timestamptz`	Время открытия свечи
`open`	`numeric`	Цена открытия
`high`	`numeric`	Максимум
`low`	`numeric`	Минимум
`close`	`numeric`	Цена закрытия
`volume`	`numeric`	Объём

`book_snapshots`¶

Снапшоты книги ордеров, используемые для восстановления состояния и исторического анализа.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор снапшота
`ticker`	`text` FK → `tickers.symbol`	Торговая пара
`bids`	`jsonb`	Массив заявок на покупку `[[price, qty], …]`
`asks`	`jsonb`	Массив заявок на продажу `[[price, qty], …]`
`created_at`	`timestamptz`	Время снапшота

Группа: Blockchain — депозиты и выводы¶

`wallets`¶

Депозитные блокчейн-адреса, привязанные к аккаунтам.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор кошелька
`account_id`	`uuid` FK → `accounts.id`	Владелец
`balance_account_id`	`uuid` FK → `balance_accounts.id`	Целевой балансовый аккаунт
`blockchain`	`text`	`btc`, `eth`, `tron` и т.д.
`address`	`text`	Адрес кошелька

`chain_topups`¶

Входящие депозиты, обнаруженные topupscan.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор депозита
`wallet_id`	`uuid` FK → `wallets.id`	Целевой кошелёк
`tx_hash`	`text`	Хэш транзакции в блокчейне
`asset`	`text`	Код актива
`amount`	`numeric`	Сумма депозита
`status`	`text`	`pending`, `aml_check`, `credited`, `rejected`, `refunded`
`detected_at`	`timestamptz`	Время обнаружения

`chain_topup_status_history`¶

Журнал смены статусов депозита.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор записи
`chain_topup_id`	`uuid` FK → `chain_topups.id`	Депозит
`status`	`text`	Новый статус
`changed_at`	`timestamptz`	Время смены

`chain_topup_aml_categories`¶

Результаты AML-проверки от Elliptic для каждого депозита.

Колонка	Тип	Описание
`chain_topup_id`	`uuid` FK → `chain_topups.id`	Депозит
`category`	`text`	Категория риска
`score`	`numeric`	Оценка риска (0–1)

`topupscan_states`¶

Состояние сканирования для каждого блокчейна.

Колонка	Тип	Описание
`blockchain`	`text` PK	Идентификатор блокчейна
`last_scanned_block`	`int8`	Последний просканированный блок

`bitcoin_utxo`¶

Учёт непотраченных выходов (UTXO) для Bitcoin-кошельков биржи.

Колонка	Тип	Описание
`tx_hash`	`text` PK	Хэш транзакции
`vout`	`int4` PK	Индекс выхода
`wallet_id`	`uuid` FK → `wallets.id`	Кошелёк
`amount`	`numeric`	Сумма в сатоши
`spent`	`bool`	Потрачен ли UTXO

`txes`¶

Исходящие транзакции на вывод средств.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор транзакции
`tx_batch_id`	`uuid` FK → `tx_batches.id`	Пакет транзакций
`blockchain`	`text`	Блокчейн
`tx_hash`	`text`	Хэш транзакции (после трансляции)
`status`	`text`	`pending`, `broadcast`, `confirmed`, `failed`
`amount`	`numeric`	Сумма
`to_address`	`text`	Адрес получателя

`tx_batches`¶

Группы транзакций для батч-обработки.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор пакета
`blockchain`	`text`	Блокчейн
`status`	`text`	`pending`, `processing`, `done`
`created_at`	`timestamptz`	Время создания

Группа: Admin — административные операции¶

`admin_manual_topup`¶

Ручные зачисления баланса, выполненные через административный интерфейс.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор операции
`account_id`	`uuid` FK → `accounts.id`	Аккаунт
`asset`	`text`	Актив
`amount`	`numeric`	Сумма
`reason`	`text`	Причина операции
`created_at`	`timestamptz`	Время

`admin_manual_withdraw`¶

Ручные списания баланса через административный интерфейс.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор операции
`account_id`	`uuid` FK → `accounts.id`	Аккаунт
`asset`	`text`	Актив
`amount`	`numeric`	Сумма
`reason`	`text`	Причина
`created_at`	`timestamptz`	Время

`admin_transfers`¶

Внутренние переводы между аккаунтами, инициированные администратором.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор перевода
`from_account_id`	`uuid` FK → `accounts.id`	Отправитель
`to_account_id`	`uuid` FK → `accounts.id`	Получатель
`asset`	`text`	Актив
`amount`	`numeric`	Сумма
`created_at`	`timestamptz`	Время

`alerts`¶

Системные алерты для мониторинга и операционного контроля.

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор алерта
`type`	`text`	Тип: `aml_hit`, `large_withdrawal`, `system_error` и т.д.
`severity`	`text`	`info`, `warning`, `critical`
`payload`	`jsonb`	Дополнительные данные
`status`	`text`	`open`, `acknowledged`, `resolved`
`created_at`	`timestamptz`	Время создания
`resolved_at`	`timestamptz`	Время разрешения

Группа: Config — конфигурация платформы¶

`assets`¶

Список торгуемых криптовалют и токенов.

Колонка	Тип	Описание
`code`	`text` PK	Код актива: `BTC`, `ETH`, `USDT`
`name`	`text`	Полное название
`decimals`	`int8`	Количество десятичных знаков
`active`	`bool`	Активен ли актив

`asset_networks`¶

Поддерживаемые сети для каждого актива (например, USDT доступен в ERC-20 и TRC-20).

Колонка	Тип	Описание
`id`	`uuid` PK	Идентификатор
`asset`	`text` FK → `assets.code`	Актив
`network`	`text`	Блокчейн-сеть
`deposit_enabled`	`bool`	Разрешены ли депозиты
`withdraw_enabled`	`bool`	Разрешены ли выводы

`tickers`¶

Торговые пары (рынки).

Колонка	Тип	Описание
`symbol`	`text` PK	Символ пары: `BTC-USDT`
`base_asset`	`text` FK → `assets.code`	Базовый актив
`quote_asset`	`text` FK → `assets.code`	Котируемый актив
`active`	`bool`	Торгуется ли пара

`risk_categories`¶

Категории AML-рисков, используемые при проверке депозитов.

Колонка	Тип	Описание
`code`	`text` PK	Код категории
`description`	`text`	Описание
`action`	`text`	Действие: `allow`, `review`, `reject`

`blacklist`¶

Заблокированные блокчейн-адреса.

Колонка	Тип	Описание
`address`	`text` PK	Адрес
`blockchain`	`text`	Блокчейн
`reason`	`text`	Причина блокировки
`added_at`	`timestamptz`	Дата добавления

`withdraw_settings`¶

Настройки ограничений и комиссий для вывода средств. Составной ключ: (asset, network).

Колонка	Тип	Описание
`asset`	`text` FK → `assets.code`	Актив
`network`	`text`	Блокчейн-сеть
`min_amount`	`numeric`	Минимальная сумма вывода
`max_amount`	`numeric`	Максимальная сумма вывода
`fee`	`numeric`	Комиссия за вывод
`enabled`	`bool`	Включён ли вывод

База данных¶

ER-диаграмма (основные связи)¶

Группа: Core — аккаунты, балансы, тарифы¶

accounts¶

balance_accounts¶

balances¶

api_keys¶

tiers¶

default_tier¶

Группа: Trading — торговля¶

orders¶

trades¶

candles¶

book_snapshots¶

Группа: Blockchain — депозиты и выводы¶

wallets¶

chain_topups¶

chain_topup_status_history¶

chain_topup_aml_categories¶

topupscan_states¶

bitcoin_utxo¶

txes¶

tx_batches¶