syntax = "proto3";

// Пакет gRPC публичного API custody-слоя (mpc_service): выдача депозитных адресов, выводы, статусы.
// Интеграция с BitGo; вызовы от gateway или внутренних сервисов с доверенной сети.
package custody.v1;

// CustodyService — операции с кастоди-кошельком от имени пользователя (без прямого доступа клиента к BitGo).
service CustodyService {
  // Выдать существующий или создать новый депозитный адрес пользователя для пары (сеть, актив).
  // При создании адрес регистрируется в Ledger через исходящий gRPC mpc → ledger.
  rpc GetOrCreateDepositAddress(GetDepositAddressRequest) returns (GetDepositAddressResponse);
  // Список всех депозитных адресов для сканирования on-chain (внутренний вызов Deposit Service и др.).
  rpc ListDepositAddresses(ListDepositAddressesRequest) returns (ListDepositAddressesResponse);
  // Инициировать вывод средств на указанный on-chain адрес; возвращает id трансфера в custody и унифицированный статус.
  rpc CreateWithdrawal(CreateWithdrawalRequest) returns (CreateWithdrawalResponse);
  // Получить текущий статус ранее созданного вывода по внешнему id заявки (withdraw_request_id).
  rpc GetWithdrawalStatus(GetWithdrawalStatusRequest) returns (GetWithdrawalStatusResponse);
  // Упрощённый статус «депозита по адресу» на стороне custody (выдача адреса / ожидание on-chain — без полного трекинга в этой БД).
  rpc GetDepositStatus(GetDepositStatusRequest) returns (GetDepositStatusResponse);
}

message ListDepositAddressesRequest {
  string network = 1;              // TRON | BSC
  string asset = 2;                // По умолчанию USDT
}

message ListDepositAddressRow {
  int64 user_id = 1;
  string network = 2;
  string asset = 3;
  string address = 4;
}

message ListDepositAddressesResponse {
  repeated ListDepositAddressRow items = 1;
}

message GetDepositAddressRequest {
  int64 user_id = 1;               // Идентификатор пользователя (на wire при longs:String — строка).
  string network = 2;              // TRON | BSC и т.д.
  string asset = 3;                // По умолчанию USDT.
}

message GetDepositAddressResponse {
  int64 user_id = 1;
  string network = 2;
  string asset = 3;
  string address = 4;              // Депозитный адрес для пополнения.
}

message CreateWithdrawalRequest {
  string withdraw_request_id = 1;  // Уникальный id заявки со стороны продукта (идемпотентность на уровне mpc/БД).
  int64 user_id = 2;
  string network = 3;
  string amount = 4;               // Сумма в decimal-строке.
  string to_address = 5;           // Адрес получателя в целевой сети.
  optional string asset = 6;       // USDT и т.д. (опционально для обратной совместимости).
}

message CreateWithdrawalResponse {
  string withdraw_request_id = 1;
  string custody_transfer_id = 2;  // Id трансфера в BitGo (исторически назывался fireblocks_tx_id).
  string mapped_status = 3;        // Унифицированный статус вывода для внутренней логики (CREATED, BROADCASTING, …).
}

message GetWithdrawalStatusRequest {
  string withdraw_request_id = 1;
}

message GetWithdrawalStatusResponse {
  string withdraw_request_id = 1;
  string custody_transfer_id = 2;
  string mapped_status = 3;
  string raw_custody_status = 4;   // Сырой статус от BitGo.
  optional string tx_hash = 5;
  optional string error_code = 6;
  optional string error_message = 7;
}

message GetDepositStatusRequest {
  int64 user_id = 1;
  string network = 2;
  string address = 3;              // Ранее выданный депозитный адрес.
  optional string tx_hash = 4;     // Опционально: подсказка по конкретной транзакции (информативно).
}

// Статус отслеживания депозита в рамках ответа GetDepositStatus (не полный on-chain индекс).
enum DepositTrackingStatus {
  DEPOSIT_TRACKING_STATUS_UNSPECIFIED = 0;
  DEPOSIT_TRACKING_STATUS_UNKNOWN = 1;   // Адрес не найден / нет данных.
  DEPOSIT_TRACKING_STATUS_PENDING = 2;    // Адрес выдан, ожидание/не подтверждено в этом сервисе.
  DEPOSIT_TRACKING_STATUS_CONFIRMED = 3;  // Подтверждено (если сервис отдаёт такой уровень детализации).
  DEPOSIT_TRACKING_STATUS_FAILED = 4;
}

message GetDepositStatusResponse {
  DepositTrackingStatus status = 1;
  string message = 2;              // Человекочитаемое пояснение (например, куда смотреть дальше — Ledger).
  optional string tx_hash = 3;
}