Exchange Integration Service¶

Назначение¶

Exchange Integration — сервис-адаптер (прокси) между внешними клиентами (прежде всего UnivexID, Gateway, Admin Gateway) и внутренним Exchange Admin gRPC биржевого движка. Помимо проксирования, сервис самостоятельно управляет биржевыми аккаунтами: регистрация и логин выполняются с хэшированием паролей.

Общее количество RPC: 60.

Архитектура¶

Сервис построен по многоуровневой архитектуре:

┌─────────────────────────────────────────────┐
│               RPC Layer                      │
│   (gRPC-сервер, обработка входящих запросов) │
└────────────────────┬────────────────────────┘
                     │
┌────────────────────▼────────────────────────┐
│             Domain Layer                     │
│  (бизнес-логика: регистрация, логин,         │
│   хэширование паролей, оркестрация вызовов)  │
└──────────┬─────────────────────┬────────────┘
           │                     │
┌──────────▼──────────┐ ┌────────▼────────────┐
│   Storage Layer     │ │   Clients Layer      │
│  (PostgreSQL,       │ │  (Exchange Admin     │
│   2 таблицы)        │ │   gRPC клиент)       │
└─────────────────────┘ └─────────────────────┘

Слой	Ответственность
RPC	Принимает входящие gRPC-запросы, сериализация/десериализация
Domain	Бизнес-логика: хэширование паролей, оркестрация Storage и Clients
Storage	CRUD операции с таблицами PostgreSQL
Clients	HTTP/gRPC-клиент для обращения к Exchange Admin gRPC

База данных¶

Миграции (2)¶

Миграция	Таблица	Описание
1	`exchange_accounts`	Биржевые аккаунты с хэшированными паролями
2	`tokens_for_exchange_account`	Токены, привязанные к биржевым аккаунтам

Схема таблиц¶

erDiagram
    exchange_accounts {
        UUID      account_id  PK  "Первичный ключ"
        TEXT      password        "Хэшированный пароль (SHA-256)"
        TIMESTAMP created_at      "Дата создания аккаунта"
    }

    tokens_for_exchange_account {
        UUID      id          PK  "Первичный ключ"
        UUID      account_id  FK  "Ссылка на exchange_accounts"
        TEXT      token           "Токен доступа"
        TIMESTAMP expires_at      "Срок действия токена"
        TIMESTAMP created_at      "Дата создания"
    }

    exchange_accounts ||--o{ tokens_for_exchange_account : "имеет"

Пароли хранятся в виде SHA-256 хэша. Сервис использует общий пакет pkg/sha256 для хэширования.

gRPC-контракт¶

Прото-файл: proto/exchange_integration.proto

Полный список RPC (60)¶

service ExchangeIntegration {

    // Аутентификация (2)
    rpc Register(RegisterRequest) returns (RegisterResponse);
    rpc Login(LoginRequest) returns (LoginResponse);

    // API-ключи (3)
    rpc ListApiKeys(ListApiKeysRequest) returns (ListApiKeysResponse);
    rpc DeleteApiKey(DeleteApiKeyRequest) returns (DeleteApiKeyResponse);
    rpc CreateApiKey(CreateApiKeyRequest) returns (CreateApiKeyResponse);

    // Аккаунты (8)
    rpc GetBalances(GetBalancesRequest) returns (GetBalancesResponse);
    rpc GetAccountDetails(GetAccountDetailsRequest) returns (GetAccountDetailsResponse);
    rpc SetTier(SetTierRequest) returns (SetTierResponse);
    rpc CreateTier(CreateTierRequest) returns (CreateTierResponse);
    rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
    rpc ChangeAccountStatus(ChangeAccountStatusRequest) returns (ChangeAccountStatusResponse);
    rpc SetAccountVIP(SetAccountVIPRequest) returns (SetAccountVIPResponse);
    rpc ListTransactions(ListTransactionsRequest) returns (ListTransactionsResponse);

    // Горячие кошельки (3)
    rpc ListHotWallets(ListHotWalletsRequest) returns (ListHotWalletsResponse);
    rpc TransferAssets(TransferAssetsRequest) returns (TransferAssetsResponse);
    rpc GetTransferAssetStatus(GetTransferAssetStatusRequest) returns (GetTransferAssetStatusResponse);

    // Транзитные кошельки (6)
    rpc ListTransitWallets(ListTransitWalletsRequest) returns (ListTransitWalletsResponse);
    rpc GetTransitWallet(GetTransitWalletRequest) returns (GetTransitWalletResponse);
    rpc CreateTransitWallet(CreateTransitWalletRequest) returns (CreateTransitWalletResponse);
    rpc BypassAML(BypassAMLRequest) returns (BypassAMLResponse);
    rpc ListWalletTopups(ListWalletTopupsRequest) returns (ListWalletTopupsResponse);
    rpc ListWalletWithdrawals(ListWalletWithdrawalsRequest) returns (ListWalletWithdrawalsResponse);

    // Информация (4)
    rpc ListNetworks(ListNetworksRequest) returns (ListNetworksResponse);
    rpc ListNetworksInfo(ListNetworksInfoRequest) returns (ListNetworksInfoResponse);
    rpc ListTiers(ListTiersRequest) returns (ListTiersResponse);
    rpc GetTier(GetTierRequest) returns (GetTierResponse);

    // Блокчейн (10)
    rpc GetDepositAddress(GetDepositAddressRequest) returns (GetDepositAddressResponse);
    rpc WithdrawToBlockchain(WithdrawToBlockchainRequest) returns (WithdrawToBlockchainResponse);
    rpc GetWithdrawRequestStatus(GetWithdrawRequestStatusRequest) returns (GetWithdrawRequestStatusResponse);
    rpc ListTopUps(ListTopUpsRequest) returns (ListTopUpsResponse);
    rpc ListAllTopUps(ListAllTopUpsRequest) returns (ListAllTopUpsResponse);
    rpc ListWithdrawals(ListWithdrawalsRequest) returns (ListWithdrawalsResponse);
    rpc GetWithdrawAvailabilityStatus(GetWithdrawAvailabilityStatusRequest) returns (GetWithdrawAvailabilityStatusResponse);
    rpc SetWithdrawAvailabilityStatus(SetWithdrawAvailabilityStatusRequest) returns (SetWithdrawAvailabilityStatusResponse);
    rpc ListBlockchainTransactions(ListBlockchainTransactionsRequest) returns (ListBlockchainTransactionsResponse);
    rpc GetTransactionHashes(GetTransactionHashesRequest) returns (GetTransactionHashesResponse);

    // Операции (6)
    rpc ManualTopup(ManualTopupRequest) returns (ManualTopupResponse);
    rpc ManualWithdraw(ManualWithdrawRequest) returns (ManualWithdrawResponse);
    rpc Transfer(TransferRequest) returns (TransferResponse);
    rpc ManualTopupBalanceAccount(ManualTopupBalanceAccountRequest) returns (ManualTopupBalanceAccountResponse);
    rpc ManualWithdrawBalanceAccount(ManualWithdrawBalanceAccountRequest) returns (ManualWithdrawBalanceAccountResponse);
    rpc TransferBalanceAccount(TransferBalanceAccountRequest) returns (TransferBalanceAccountResponse);

    // Активы (6)
    rpc ListAssets(ListAssetsRequest) returns (ListAssetsResponse);
    rpc GetAssetStatus(GetAssetStatusRequest) returns (GetAssetStatusResponse);
    rpc SetAssetTradingEnabled(SetAssetTradingEnabledRequest) returns (SetAssetTradingEnabledResponse);
    rpc SetNetworkAssetAliasEnabledTopup(SetNetworkAssetAliasEnabledTopupRequest) returns (SetNetworkAssetAliasEnabledTopupResponse);
    rpc SetNetworkAssetAliasEnabledWithdraw(SetNetworkAssetAliasEnabledWithdrawRequest) returns (SetNetworkAssetAliasEnabledWithdrawResponse);
    rpc SetNetworkAssetAliasWithdrawCommission(SetNetworkAssetAliasWithdrawCommissionRequest) returns (SetNetworkAssetAliasWithdrawCommissionResponse);

    // Тикеры (2)
    rpc ListTickers(ListTickersRequest) returns (ListTickersResponse);
    rpc SetTickerTradingEnabled(SetTickerTradingEnabledRequest) returns (SetTickerTradingEnabledResponse);

    // Категории риска (4)
    rpc GetCategories(GetCategoriesRequest) returns (GetCategoriesResponse);
    rpc SetCategoryThresholds(SetCategoryThresholdsRequest) returns (SetCategoryThresholdsResponse);
    rpc RenameRiskCategory(RenameRiskCategoryRequest) returns (RenameRiskCategoryResponse);
    rpc ListBlacklistedAddresses(ListBlacklistedAddressesRequest) returns (ListBlacklistedAddressesResponse);

    // AML / Refund (6)
    rpc AmlDecisionClean(AmlDecisionCleanRequest) returns (AmlDecisionCleanResponse);
    rpc AmlDecisionRefund(AmlDecisionRefundRequest) returns (AmlDecisionRefundResponse);
    rpc SetRefundAddress(SetRefundAddressRequest) returns (SetRefundAddressResponse);
    rpc ListTopupStatusHistory(ListTopupStatusHistoryRequest) returns (ListTopupStatusHistoryResponse);
    rpc DeleteRiskCategories(DeleteRiskCategoriesRequest) returns (DeleteRiskCategoriesResponse);
    rpc GetTopupDetails(GetTopupDetailsRequest) returns (GetTopupDetailsResponse);

    // Конфигурация (1)
    rpc ValidateConfig(ValidateConfigRequest) returns (ValidateConfigResponse);
}

Группы RPC¶

Аутентификация (2)¶

RPC	Описание
`Register`	Регистрирует новый биржевой аккаунт. Создаёт запись в `exchange_accounts`, хэширует пароль (SHA-256).
`Login`	Аутентифицирует аккаунт по UUID и паролю. Сверяет SHA-256 хэш.

API-ключи (3)¶

RPC	Описание
`ListApiKeys`	Возвращает список API-ключей аккаунта.
`CreateApiKey`	Создаёт новый API-ключ для аккаунта.
`DeleteApiKey`	Удаляет API-ключ по идентификатору.

Управление аккаунтами (8)¶

RPC	Описание
`GetBalances`	Возвращает балансы аккаунта по всем активам.
`GetAccountDetails`	Возвращает детальную информацию об аккаунте.
`SetTier`	Устанавливает торговый уровень (tier) аккаунта.
`CreateTier`	Создаёт новый торговый уровень (tier).
`ListOrders`	Возвращает список ордеров аккаунта с фильтрацией.
`ChangeAccountStatus`	Изменяет статус аккаунта (активен, заблокирован и т.д.).
`SetAccountVIP`	Устанавливает/снимает VIP-статус аккаунта.
`ListTransactions`	Возвращает список транзакций аккаунта.

Горячие кошельки (3)¶

RPC	Описание
`ListHotWallets`	Возвращает список горячих кошельков.
`TransferAssets`	Инициирует перевод активов между кошельками.
`GetTransferAssetStatus`	Возвращает статус перевода активов.

Транзитные кошельки (6)¶

RPC	Описание
`ListTransitWallets`	Возвращает список транзитных кошельков.
`GetTransitWallet`	Возвращает данные конкретного транзитного кошелька.
`CreateTransitWallet`	Создаёт новый транзитный кошелёк.
`BypassAML`	Помечает пополнение транзитного кошелька как прошедшее AML без проверки.
`ListWalletTopups`	Возвращает историю пополнений транзитного кошелька.
`ListWalletWithdrawals`	Возвращает историю выводов с транзитного кошелька.

Информация (4)¶

RPC	Описание
`ListNetworks`	Возвращает список поддерживаемых блокчейн-сетей.
`ListNetworksInfo`	Возвращает расширенную информацию о сетях (комиссии, минимальные суммы).
`ListTiers`	Возвращает список доступных торговых уровней.
`GetTier`	Возвращает данные конкретного торгового уровня.

Блокчейн-операции (10)¶

RPC	Описание
`GetDepositAddress`	Возвращает адрес для пополнения по сети и аккаунту.
`WithdrawToBlockchain`	Инициирует вывод средств в блокчейн.
`GetWithdrawRequestStatus`	Возвращает статус запроса на вывод.
`ListTopUps`	Возвращает список пополнений аккаунта.
`ListAllTopUps`	Возвращает список всех пополнений (для администраторов).
`ListWithdrawals`	Возвращает список выводов.
`GetWithdrawAvailabilityStatus`	Проверяет, доступен ли вывод для актива/сети.
`SetWithdrawAvailabilityStatus`	Включает/выключает возможность вывода для актива/сети.
`ListBlockchainTransactions`	Возвращает список блокчейн-транзакций.
`GetTransactionHashes`	Возвращает хэши транзакций по идентификатору вывода.

Ручные операции (6)¶

RPC	Описание
`ManualTopup`	Ручное пополнение торгового баланса.
`ManualWithdraw`	Ручной вывод с торгового баланса.
`Transfer`	Перевод между торговыми аккаунтами.
`ManualTopupBalanceAccount`	Ручное пополнение балансового аккаунта.
`ManualWithdrawBalanceAccount`	Ручной вывод с балансового аккаунта.
`TransferBalanceAccount`	Перевод между балансовыми аккаунтами.

Активы (6)¶

RPC	Описание
`ListAssets`	Возвращает список всех активов.
`GetAssetStatus`	Возвращает статус актива (торговля, пополнение, вывод).
`SetAssetTradingEnabled`	Включает/выключает торговлю активом.
`SetNetworkAssetAliasEnabledTopup`	Включает/выключает пополнение для актива/сети.
`SetNetworkAssetAliasEnabledWithdraw`	Включает/выключает вывод для актива/сети.
`SetNetworkAssetAliasWithdrawCommission`	Устанавливает комиссию на вывод для актива/сети.

Тикеры (2)¶

RPC	Описание
`ListTickers`	Возвращает список всех торговых пар (тикеров).
`SetTickerTradingEnabled`	Включает/выключает торговлю по паре.

Категории риска (4)¶

RPC	Описание
`GetCategories`	Возвращает список категорий риска с порогами.
`SetCategoryThresholds`	Устанавливает пороговые значения для категории риска.
`RenameRiskCategory`	Переименовывает категорию риска.
`ListBlacklistedAddresses`	Возвращает список адресов из чёрного списка.

AML / Refund (6)¶

RPC	Описание
`AmlDecisionClean`	Помечает пополнение как чистое (AML пройден).
`AmlDecisionRefund`	Инициирует возврат средств по пополнению (AML не пройден).
`SetRefundAddress`	Устанавливает адрес возврата для аккаунта.
`ListTopupStatusHistory`	Возвращает историю смены статусов пополнения.
`DeleteRiskCategories`	Удаляет категории риска.
`GetTopupDetails`	Возвращает детали пополнения включая AML-информацию.

Конфигурация (1)¶

RPC	Описание
`ValidateConfig`	Валидирует конфигурацию биржевого движка.

Типы и перечисления¶

Network — блокчейн-сеть¶

enum Network {
    NETWORK_UNSPECIFIED = 0;
    ETHEREUM = 1;
    TRON     = 2;
    BITCOIN  = 3;
}

TxStatus — статус транзакции¶

enum TxStatus {
    TX_STATUS_UNSPECIFIED = 0;
    TX_STATUS_PENDING     = 1;
    TX_STATUS_COMPLETED   = 2;
    TX_STATUS_FAILED      = 3;
}

AccountStatus — статус аккаунта¶

enum AccountStatus {
    ACCOUNT_STATUS_UNSPECIFIED = 0;
    ACCOUNT_STATUS_ACTIVE      = 1;
    ACCOUNT_STATUS_SUSPENDED   = 2;
    ACCOUNT_STATUS_BLOCKED     = 3;
}

OrderType — тип ордера¶

enum OrderType {
    ORDER_TYPE_UNSPECIFIED = 0;
    ORDER_TYPE_LIMIT       = 1;
    ORDER_TYPE_MARKET      = 2;
}

OrderStatus — статус ордера¶

enum OrderStatus {
    ORDER_STATUS_UNSPECIFIED = 0;
    ORDER_STATUS_OPEN        = 1;
    ORDER_STATUS_FILLED      = 2;
    ORDER_STATUS_CANCELLED   = 3;
    ORDER_STATUS_PARTIAL     = 4;
}

OrderDir — направление ордера¶

enum OrderDir {
    ORDER_DIR_UNSPECIFIED = 0;
    ORDER_DIR_BUY         = 1;
    ORDER_DIR_SELL        = 2;
}

BalanceAccountType — тип балансового аккаунта¶

enum BalanceAccountType {
    BALANCE_ACCOUNT_TYPE_UNSPECIFIED = 0;
    BALANCE_ACCOUNT_TYPE_TRADING     = 1;
    BALANCE_ACCOUNT_TYPE_BALANCE     = 2;
}

Коды ошибок¶

Операция	Код ошибки	Описание
`Register`	`ALREADY_EXISTS`	Аккаунт с таким ID уже зарегистрирован
`Register`	`INTERNAL`	Ошибка при создании аккаунта в движке
`Login`	`NOT_FOUND`	Аккаунт не найден
`Login`	`UNAUTHENTICATED`	Неверный пароль
`GetBalances`	`NOT_FOUND`	Аккаунт не найден
`CreateApiKey`	`PERMISSION_DENIED`	Недостаточно прав
`DeleteApiKey`	`NOT_FOUND`	Ключ не найден
`WithdrawToBlockchain`	`FAILED_PRECONDITION`	Недостаточно средств
`GetWithdrawRequestStatus`	`NOT_FOUND`	Запрос не найден
`GetDepositAddress`	`INVALID_ARGUMENT`	Неверная сеть или аккаунт
`ChangeAccountStatus`	`NOT_FOUND`	Аккаунт не найден
`SetTier`	`INVALID_ARGUMENT`	Неверный tier
`TransferAssets`	`FAILED_PRECONDITION`	Недостаточно средств на кошельке
`AmlDecisionRefund`	`FAILED_PRECONDITION`	Адрес возврата не установлен
Любой RPC	`UNAVAILABLE`	Exchange Admin gRPC недоступен

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

Параметр	Описание
`EXCHANGE_ADMIN_GRPC_ADDR`	Адрес Exchange Admin gRPC сервера
`DATABASE_URL`	DSN для подключения к PostgreSQL
`GRPC_PORT`	Порт gRPC-сервера (по умолчанию `50051`)