Перейти к содержанию

Управление балансами

В данном разделе описана структура балансовых счетов пользователей Univex, правила изменения балансов и доступные операции — как пользовательские, так и административные.

Архитектура: сервис Ledger

Все финансовые операции с балансами пользователей выполняются через сервис Ledger:

  • Пользователи обращаются к балансовым операциям через Gateway → Ledger.
  • Администраторы выполняют ручные операции через AdminGateway → Ledger.
  • Ledger отвечает за: балансы, фиатные операции, переводы между счетами, замороженные активы, фанд-коды (funded codes), блокчейн-выводы (через ExchangeIntegration).

Структура счетов

Каждый пользовательский аккаунт имеет строго определённую иерархию балансовых объектов:

graph TD
    ACC[Account\nпользовательский аккаунт] --> F[BalanceAccount\nFUNDING]
    ACC --> T[BalanceAccount\nTRADING]

    F --> FB1[Balance\nBTC]
    F --> FB2[Balance\nUSDT]
    F --> FB3[Balance\n...]

    T --> TB1[Balance\nBTC]
    T --> TB2[Balance\nUSDT]
    T --> TB3[Balance\n...]

    ACC --> SUB1[Subaccount 1]
    ACC --> SUB2[Subaccount 2]

    SUB1 --> SF1[BalanceAccount\nFUNDING]
    SUB1 --> ST1[BalanceAccount\nTRADING]

    style ACC fill:#4a90d9,color:#fff
    style F fill:#7b68ee,color:#fff
    style T fill:#7b68ee,color:#fff
    style SUB1 fill:#5aaa8a,color:#fff
    style SUB2 fill:#5aaa8a,color:#fff

Типы балансовых счетов

Тип Назначение
FUNDING Хранение депозитов и свободных средств. Источник/получатель для вводов и выводов
TRADING Средства, доступные для торговли. Ордера резервируют средства на этом счёте

Субаккаунты

  • Субаккаунты создаются под основным (master) аккаунтом.
  • Субаккаунты наследуют тарифный уровень (tier) от основного аккаунта.
  • Каждый субаккаунт имеет собственные независимые FUNDING и TRADING балансовые счета.

Структура объекта Balance

Каждый баланс идентифицируется составным ключом:

(balance_account_id, asset) → Balance {available, reserved}
Поле Описание
available Свободные средства, доступные для операций
reserved Средства, заблокированные под открытые ордера
total available + reserved

Операции с балансами

1. Внутренний перевод (FUNDING ↔ TRADING)

Пользователь самостоятельно переводит средства между своими счетами через Gateway → Ledger:

POST /balances/transfer  (через Gateway → Ledger)
{
  "asset": "USDT",
  "amount": "1000.00",
  "direction": "funding_to_trading"  // или "trading_to_funding"
}
  • Операция атомарна: списание и зачисление происходят в одной транзакции БД.
  • Перевод мгновенный, без комиссии.

2. Фиатные операции

Пользователь может пополнить FUNDING-счёт через фиатный канал (банковский перевод, карта) и вывести фиат. Все фиатные операции проходят через Gateway → Ledger:

  • Ledger создаёт запись фиатной заявки (fiat bid).
  • Администратор подтверждает через AdminGateway → Ledger.
  • После подтверждения Ledger зачисляет или списывает баланс.

3. Замороженные активы

Ledger поддерживает заморозку средств (например, при открытых спорах P2P или административных задержаниях):

  • Средства переводятся из available в frozen состояние.
  • Разморозка выполняется вручную администратором или автоматически по завершении процесса.

4. Фанд-коды (Funded Codes)

Пользователи могут пополнять баланс через активацию фанд-кодов:

  • Пользователь вводит код через Gateway → Ledger.
  • Ledger проверяет код и зачисляет указанную сумму на FUNDING-счёт.

5. Ручное пополнение (Admin Manual Topup)

Администратор может зачислить средства на счёт пользователя через AdminGateway → Ledger:

AdminGateway → Ledger.ManualTopup(account_id, asset, amount, reason)
  • Используется для компенсаций, бонусов, корректировок.
  • Операция логируется с указанием причины (reason) и ID администратора.

6. Ручное списание (Admin Manual Withdraw)

Администратор может списать средства со счёта пользователя через AdminGateway → Ledger:

AdminGateway → Ledger.ManualWithdraw(account_id, asset, amount, reason)
  • Используется при возвратах, штрафах, корректировках.
  • Требует наличия достаточного available баланса.

7. Перевод между пользователями (Admin Transfer)

Администратор может перевести средства между аккаунтами через AdminGateway → Ledger:

AdminGateway → Ledger.Transfer(from_account_id, to_account_id, asset, amount, reason)

8. Расчёт по торговым сделкам (Trading Settlement)

При исполнении ордеров Exchange Engine атомарно обновляет балансы покупателя и продавца:

  • Из reserved покупателя списывается сумма в базовой валюте.
  • На available покупателя зачисляется котируемая валюта.
  • Из reserved продавца списывается котируемая валюта.
  • На available продавца зачисляется базовая валюта.
  • Торговые комиссии удерживаются в момент расчёта.

Правила обновления балансов

Все изменения балансов подчиняются строгим правилам атомарности:

flowchart LR
    subgraph Размещение ордера
        A1[available] -->|резервирование| B1[reserved]
    end

    subgraph Исполнение сделки
        B2[reserved покупателя] -->|списание| C2[расчёт]
        C2 -->|зачисление| D2[available продавца]
    end

    subgraph Отмена ордера
        B3[reserved] -->|освобождение| A3[available]
    end
Событие Изменение баланса
Размещение LIMIT ордера available уменьшается, reserved увеличивается
Исполнение сделки reserved уменьшается у продавца/покупателя; available увеличивается у контрагента
Отмена ордера reserved уменьшается, available восстанавливается
Депозит available на FUNDING увеличивается
Вывод available на FUNDING уменьшается
Перевод FUNDING→TRADING available на FUNDING уменьшается; available на TRADING увеличивается
Заморозка available уменьшается, frozen увеличивается
Разморозка frozen уменьшается, available восстанавливается

Атомарность и целостность данных

  • Все операции с балансами выполняются в транзакциях базы данных с отложенными ограничениями (deferred constraints).
  • Это гарантирует, что промежуточное состояние баланса (например, после списания, но до зачисления) не видно другим процессам.
  • Отрицательные значения available или reserved недопустимы и блокируются на уровне ограничений БД.
  • Все изменения балансов фиксируются в журнале операций для аудита.

Связанные разделы