@arbiwallet/contracts 1.0.22 → 1.0.24

package/gen/aml.ts

@@ -0,0 +1,92 @@
+// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
+// versions:
+//   protoc-gen-ts_proto  v2.11.4
+//   protoc               v7.34.0
+// source: aml.proto
+
+/* eslint-disable */
+import { GrpcMethod, GrpcStreamMethod } from "@nestjs/microservices";
+import { Observable } from "rxjs";
+
+export const protobufPackage = "aml.v1";
+
+export enum AmlDecision {
+  ALLOW = 0,
+  REVIEW = 1,
+  BLOCK = 2,
+  UNRECOGNIZED = -1,
+}
+
+export interface ScreenDepositRequest {
+  network: string;
+  asset: string;
+  txHash: string;
+  fromAddress: string;
+  toAddress: string;
+  amount: string;
+  confirmedAtUnix: number;
+  idempotencyKey: string;
+}
+
+export interface ScreenWithdrawalRequest {
+  network: string;
+  asset: string;
+  toAddress: string;
+  amount: string;
+  idempotencyKey: string;
+}
+
+export interface ScreenResponse {
+  decision: AmlDecision;
+  score: number;
+  reason: string;
+  provider: string;
+  providerRef: string;
+  rawStatus: string;
+  isFinal: boolean;
+}
+
+export interface HealthRequest {
+}
+
+export interface HealthResponse {
+  ok: boolean;
+  version: string;
+}
+
+export const AML_V1_PACKAGE_NAME = "aml.v1";
+
+export interface AmlServiceClient {
+  screenDeposit(request: ScreenDepositRequest): Observable<ScreenResponse>;
+
+  screenWithdrawal(request: ScreenWithdrawalRequest): Observable<ScreenResponse>;
+
+  health(request: HealthRequest): Observable<HealthResponse>;
+}
+
+export interface AmlServiceController {
+  screenDeposit(request: ScreenDepositRequest): Promise<ScreenResponse> | Observable<ScreenResponse> | ScreenResponse;
+
+  screenWithdrawal(
+    request: ScreenWithdrawalRequest,
+  ): Promise<ScreenResponse> | Observable<ScreenResponse> | ScreenResponse;
+
+  health(request: HealthRequest): Promise<HealthResponse> | Observable<HealthResponse> | HealthResponse;
+}
+
+export function AmlServiceControllerMethods() {
+  return function (constructor: Function) {
+    const grpcMethods: string[] = ["screenDeposit", "screenWithdrawal", "health"];
+    for (const method of grpcMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcMethod("AmlService", method)(constructor.prototype[method], method, descriptor);
+    }
+    const grpcStreamMethods: string[] = [];
+    for (const method of grpcStreamMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcStreamMethod("AmlService", method)(constructor.prototype[method], method, descriptor);
+    }
+  };
+}
+
+export const AML_SERVICE_NAME = "AmlService";

package/gen/custody.ts

@@ -23,6 +23,24 @@ export enum DepositTrackingStatus {
   UNRECOGNIZED = -1,
 }
 
+export interface ListDepositAddressesRequest {
+  /** TRON | BSC */
+  network: string;
+  /** По умолчанию USDT */
+  asset: string;
+}
+
+export interface ListDepositAddressRow {
+  userId: number;
+  network: string;
+  asset: string;
+  address: string;
+}
+
+export interface ListDepositAddressesResponse {
+  items: ListDepositAddressRow[];
+}
+
 export interface GetDepositAddressRequest {
   /** Идентификатор пользователя (на wire при longs:String — строка). */
   userId: number;
@@ -49,6 +67,8 @@ export interface CreateWithdrawalRequest {
   amount: string;
   /** Адрес получателя в целевой сети. */
   toAddress: string;
+  /** USDT и т.д. (опционально для обратной совместимости). */
+  asset?: string | undefined;
 }
 
 export interface CreateWithdrawalResponse {
@@ -102,6 +122,10 @@ export interface CustodyServiceClient {
 
   getOrCreateDepositAddress(request: GetDepositAddressRequest): Observable<GetDepositAddressResponse>;
 
+  /** Список всех депозитных адресов для сканирования on-chain (внутренний вызов Deposit Service и др.). */
+
+  listDepositAddresses(request: ListDepositAddressesRequest): Observable<ListDepositAddressesResponse>;
+
   /** Инициировать вывод средств на указанный on-chain адрес; возвращает id трансфера в custody и унифицированный статус. */
 
   createWithdrawal(request: CreateWithdrawalRequest): Observable<CreateWithdrawalResponse>;
@@ -127,6 +151,12 @@ export interface CustodyServiceController {
     request: GetDepositAddressRequest,
   ): Promise<GetDepositAddressResponse> | Observable<GetDepositAddressResponse> | GetDepositAddressResponse;
 
+  /** Список всех депозитных адресов для сканирования on-chain (внутренний вызов Deposit Service и др.). */
+
+  listDepositAddresses(
+    request: ListDepositAddressesRequest,
+  ): Promise<ListDepositAddressesResponse> | Observable<ListDepositAddressesResponse> | ListDepositAddressesResponse;
+
   /** Инициировать вывод средств на указанный on-chain адрес; возвращает id трансфера в custody и унифицированный статус. */
 
   createWithdrawal(
@@ -150,6 +180,7 @@ export function CustodyServiceControllerMethods() {
   return function (constructor: Function) {
     const grpcMethods: string[] = [
       "getOrCreateDepositAddress",
+      "listDepositAddresses",
       "createWithdrawal",
       "getWithdrawalStatus",
       "getDepositStatus",

package/gen/deposit.ts

@@ -0,0 +1,60 @@
+// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
+// versions:
+//   protoc-gen-ts_proto  v2.11.4
+//   protoc               v7.34.0
+// source: deposit.proto
+
+/* eslint-disable */
+import { GrpcMethod, GrpcStreamMethod } from "@nestjs/microservices";
+import { Observable } from "rxjs";
+
+export const protobufPackage = "deposit.v1";
+
+export interface ApplyBitGoCustodyAckRequest {
+  /** TRON | BSC */
+  network: string;
+  txHash: string;
+  logIndex?: number | undefined;
+  bitgoTransferId: string;
+  bitgoState: string;
+  /** может быть пустым */
+  webhookEventId: string;
+}
+
+export interface ApplyBitGoCustodyAckResponse {
+  matched: number;
+  depositTxIds: string[];
+}
+
+export const DEPOSIT_V1_PACKAGE_NAME = "deposit.v1";
+
+export interface DepositIntegrationClient {
+  /** Привязать событие BitGo к уже найденному ончейн-депозиту (mpc webhook). */
+
+  applyBitGoCustodyAck(request: ApplyBitGoCustodyAckRequest): Observable<ApplyBitGoCustodyAckResponse>;
+}
+
+export interface DepositIntegrationController {
+  /** Привязать событие BitGo к уже найденному ончейн-депозиту (mpc webhook). */
+
+  applyBitGoCustodyAck(
+    request: ApplyBitGoCustodyAckRequest,
+  ): Promise<ApplyBitGoCustodyAckResponse> | Observable<ApplyBitGoCustodyAckResponse> | ApplyBitGoCustodyAckResponse;
+}
+
+export function DepositIntegrationControllerMethods() {
+  return function (constructor: Function) {
+    const grpcMethods: string[] = ["applyBitGoCustodyAck"];
+    for (const method of grpcMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcMethod("DepositIntegration", method)(constructor.prototype[method], method, descriptor);
+    }
+    const grpcStreamMethods: string[] = [];
+    for (const method of grpcStreamMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcStreamMethod("DepositIntegration", method)(constructor.prototype[method], method, descriptor);
+    }
+  };
+}
+
+export const DEPOSIT_INTEGRATION_SERVICE_NAME = "DepositIntegration";

package/gen/kyc_gate.ts

@@ -0,0 +1,49 @@
+// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
+// versions:
+//   protoc-gen-ts_proto  v2.11.4
+//   protoc               v7.34.0
+// source: kyc_gate.proto
+
+/* eslint-disable */
+import { GrpcMethod, GrpcStreamMethod } from "@nestjs/microservices";
+import { Observable } from "rxjs";
+
+export const protobufPackage = "kyc.v1";
+
+export interface IsWithdrawalAllowedRequest {
+  userId: string;
+}
+
+export interface IsWithdrawalAllowedResponse {
+  allowed: boolean;
+  reason: string;
+}
+
+export const KYC_V1_PACKAGE_NAME = "kyc.v1";
+
+export interface KycGateServiceClient {
+  isWithdrawalAllowed(request: IsWithdrawalAllowedRequest): Observable<IsWithdrawalAllowedResponse>;
+}
+
+export interface KycGateServiceController {
+  isWithdrawalAllowed(
+    request: IsWithdrawalAllowedRequest,
+  ): Promise<IsWithdrawalAllowedResponse> | Observable<IsWithdrawalAllowedResponse> | IsWithdrawalAllowedResponse;
+}
+
+export function KycGateServiceControllerMethods() {
+  return function (constructor: Function) {
+    const grpcMethods: string[] = ["isWithdrawalAllowed"];
+    for (const method of grpcMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcMethod("KycGateService", method)(constructor.prototype[method], method, descriptor);
+    }
+    const grpcStreamMethods: string[] = [];
+    for (const method of grpcStreamMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcStreamMethod("KycGateService", method)(constructor.prototype[method], method, descriptor);
+    }
+  };
+}
+
+export const KYC_GATE_SERVICE_NAME = "KycGateService";

package/gen/ledger.ts

@@ -50,7 +50,11 @@ export interface CreditUserBalanceRequest {
   /** Ключ идемпотентности вызова. */
   idempotencyKey: string;
   /** Опционально: число подтверждений на момент зачисления. */
-  confirmations?: number | undefined;
+  confirmations?:
+    | number
+    | undefined;
+  /** Для EVM: индекс лога; для TRON — 0 или не задано. */
+  logIndex?: number | undefined;
 }
 
 export interface CreditUserBalanceResponse {
@@ -64,6 +68,55 @@ export interface CreditUserBalanceResponse {
   total: string;
 }
 
+export interface CreditDepositHoldRequest {
+  userId: string;
+  asset: string;
+  network: string;
+  amount: string;
+  txHash: string;
+  externalOperationId: string;
+  idempotencyKey: string;
+  confirmations?: number | undefined;
+  logIndex?: number | undefined;
+}
+
+export interface CreditDepositHoldResponse {
+  depositId: string;
+  ledgerOperationId: string;
+  available: string;
+  reserved: string;
+  total: string;
+}
+
+export interface ReleaseDepositHoldRequest {
+  userId: string;
+  externalOperationId: string;
+  idempotencyKey: string;
+}
+
+export interface ReleaseDepositHoldResponse {
+  depositId: string;
+  ledgerOperationId: string;
+  available: string;
+  reserved: string;
+  total: string;
+}
+
+export interface ForfeitDepositHoldRequest {
+  userId: string;
+  externalOperationId: string;
+  idempotencyKey: string;
+  reason: string;
+}
+
+export interface ForfeitDepositHoldResponse {
+  depositId: string;
+  ledgerOperationId: string;
+  available: string;
+  reserved: string;
+  total: string;
+}
+
 export interface RegisterWithdrawalRequest {
   userId: string;
   asset: string;
@@ -240,6 +293,18 @@ export interface LedgerServiceClient {
 
   creditUserBalance(request: CreditUserBalanceRequest): Observable<CreditUserBalanceResponse>;
 
+  /** Зачисление депозита в резерв (AML review): total и reserved растут, available без изменений. */
+
+  creditDepositHold(request: CreditDepositHoldRequest): Observable<CreditDepositHoldResponse>;
+
+  /** Перевод суммы из резерва в available (админ: HELD → зачислено). */
+
+  releaseDepositHold(request: ReleaseDepositHoldRequest): Observable<ReleaseDepositHoldResponse>;
+
+  /** Списание из резерва и уменьшение total без возврата в available (блокировка / compliance). */
+
+  forfeitDepositHold(request: ForfeitDepositHoldRequest): Observable<ForfeitDepositHoldResponse>;
+
   /** Создание записи о выводе в учёте (черновик заявки); дальнейшие шаги — резерв, смена статусов, финализация. */
 
   registerWithdrawal(request: RegisterWithdrawalRequest): Observable<RegisterWithdrawalResponse>;
@@ -289,6 +354,24 @@ export interface LedgerServiceController {
     request: CreditUserBalanceRequest,
   ): Promise<CreditUserBalanceResponse> | Observable<CreditUserBalanceResponse> | CreditUserBalanceResponse;
 
+  /** Зачисление депозита в резерв (AML review): total и reserved растут, available без изменений. */
+
+  creditDepositHold(
+    request: CreditDepositHoldRequest,
+  ): Promise<CreditDepositHoldResponse> | Observable<CreditDepositHoldResponse> | CreditDepositHoldResponse;
+
+  /** Перевод суммы из резерва в available (админ: HELD → зачислено). */
+
+  releaseDepositHold(
+    request: ReleaseDepositHoldRequest,
+  ): Promise<ReleaseDepositHoldResponse> | Observable<ReleaseDepositHoldResponse> | ReleaseDepositHoldResponse;
+
+  /** Списание из резерва и уменьшение total без возврата в available (блокировка / compliance). */
+
+  forfeitDepositHold(
+    request: ForfeitDepositHoldRequest,
+  ): Promise<ForfeitDepositHoldResponse> | Observable<ForfeitDepositHoldResponse> | ForfeitDepositHoldResponse;
+
   /** Создание записи о выводе в учёте (черновик заявки); дальнейшие шаги — резерв, смена статусов, финализация. */
 
   registerWithdrawal(
@@ -346,6 +429,9 @@ export function LedgerServiceControllerMethods() {
     const grpcMethods: string[] = [
       "registerDepositAddress",
       "creditUserBalance",
+      "creditDepositHold",
+      "releaseDepositHold",
+      "forfeitDepositHold",
       "registerWithdrawal",
       "reserveFunds",
       "releaseFunds",

package/gen/webhook.ts

@@ -12,7 +12,7 @@ export const protobufPackage = "webhook.v1";
 
 export interface ProcessWebhookRequest {
   /**
-   * Полное тело webhook от BitGo в виде одной JSON-строки (как получено после парсинга HTTP, объекты сериализованы стандартно).
+   * Полное тело события от BitGo в виде одной JSON-строки (как передал gateway после приёма webhook).
    * Клиент (gateway) обязан передавать валидный JSON; mpc парсит и маппит поля transfer / state / data и т.д.
    */
   jsonPayload: string;
@@ -30,7 +30,7 @@ export const WEBHOOK_V1_PACKAGE_NAME = "webhook.v1";
 export interface WebhookServiceClient {
   /**
    * Обработка одного события webhook BitGo: разбор JSON, дедупликация по event_id, обновление custody-транзакций,
-   * при необходимости — gRPC в Ledger (статус вывода, зачисление депозита) и уведомления.
+   * при необходимости — gRPC в Ledger (статус вывода, зачисление депозита).
    */
 
   processBitGoWebhook(request: ProcessWebhookRequest): Observable<ProcessWebhookResponse>;
@@ -39,7 +39,7 @@ export interface WebhookServiceClient {
 export interface WebhookServiceController {
   /**
    * Обработка одного события webhook BitGo: разбор JSON, дедупликация по event_id, обновление custody-транзакций,
-   * при необходимости — gRPC в Ledger (статус вывода, зачисление депозита) и уведомления.
+   * при необходимости — gRPC в Ledger (статус вывода, зачисление депозита).
    */
 
   processBitGoWebhook(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arbiwallet/contracts",
   "descriptions": "Generate and manage smart contracts for ArbiWallet",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "scripts": {
     "generate": "protoc -I ./proto ./proto/*.proto --ts_proto_out=./gen --ts_proto_opt=nestJs=true,package=omit"
   },

package/proto/aml.proto

@@ -0,0 +1,51 @@
+syntax = "proto3";
+
+package aml.v1;
+
+service AmlService {
+  rpc ScreenDeposit(ScreenDepositRequest) returns (ScreenResponse);
+  rpc ScreenWithdrawal(ScreenWithdrawalRequest) returns (ScreenResponse);
+  rpc Health(HealthRequest) returns (HealthResponse);
+}
+
+enum AmlDecision {
+  ALLOW = 0;
+  REVIEW = 1;
+  BLOCK = 2;
+}
+
+message ScreenDepositRequest {
+  string network = 1;
+  string asset = 2;
+  string tx_hash = 3;
+  string from_address = 4;
+  string to_address = 5;
+  string amount = 6;
+  int64 confirmed_at_unix = 7;
+  string idempotency_key = 8;
+}
+
+message ScreenWithdrawalRequest {
+  string network = 1;
+  string asset = 2;
+  string to_address = 3;
+  string amount = 4;
+  string idempotency_key = 5;
+}
+
+message ScreenResponse {
+  AmlDecision decision = 1;
+  int32 score = 2;
+  string reason = 3;
+  string provider = 4;
+  string provider_ref = 5;
+  string raw_status = 6;
+  bool is_final = 7;
+}
+
+message HealthRequest {}
+
+message HealthResponse {
+  bool ok = 1;
+  string version = 2;
+}

package/proto/custody.proto

@@ -9,6 +9,8 @@ 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).
@@ -17,6 +19,22 @@ service CustodyService {
   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 и т.д.
@@ -36,6 +54,7 @@ message CreateWithdrawalRequest {
   string network = 3;
   string amount = 4;               // Сумма в decimal-строке.
   string to_address = 5;           // Адрес получателя в целевой сети.
+  optional string asset = 6;       // USDT и т.д. (опционально для обратной совместимости).
 }
 
 message CreateWithdrawalResponse {

package/proto/deposit.proto

@@ -0,0 +1,27 @@
+syntax = "proto3";
+
+// Внутренний gRPC deposit_service (ончейн-депозиты, привязка BitGo и т.п.).
+package deposit.v1;
+
+option csharp_namespace = "Deposit.V1";
+option java_multiple_files = true;
+option java_package = "com.arbiwallet.deposit.v1";
+
+service DepositIntegration {
+  // Привязать событие BitGo к уже найденному ончейн-депозиту (mpc webhook).
+  rpc ApplyBitGoCustodyAck(ApplyBitGoCustodyAckRequest) returns (ApplyBitGoCustodyAckResponse);
+}
+
+message ApplyBitGoCustodyAckRequest {
+  string network = 1;              // TRON | BSC
+  string tx_hash = 2;
+  optional int32 log_index = 3;
+  string bitgo_transfer_id = 4;
+  string bitgo_state = 5;
+  string webhook_event_id = 6;     // может быть пустым
+}
+
+message ApplyBitGoCustodyAckResponse {
+  int32 matched = 1;
+  repeated string deposit_tx_ids = 2;
+}

package/proto/kyc_gate.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+
+// Опциональный сервис проверки права на вывод (KYC / compliance gate).
+// Реализация — отдельный микросервис; при отключённой проверке Withdrawal Service не вызывает RPC.
+package kyc.v1;
+
+service KycGateService {
+  rpc IsWithdrawalAllowed(IsWithdrawalAllowedRequest) returns (IsWithdrawalAllowedResponse);
+}
+
+message IsWithdrawalAllowedRequest {
+  string user_id = 1;
+}
+
+message IsWithdrawalAllowedResponse {
+  bool allowed = 1;
+  string reason = 2;
+}
+

package/proto/ledger.proto

@@ -13,6 +13,12 @@ service LedgerService {
   rpc RegisterDepositAddress(RegisterDepositAddressRequest) returns (RegisterDepositAddressResponse);
   // Зачисление средств на доступный баланс пользователя (подтверждённый депозит); идемпотентность по ключу и внешнему id операции.
   rpc CreditUserBalance(CreditUserBalanceRequest) returns (CreditUserBalanceResponse);
+  // Зачисление депозита в резерв (AML review): total и reserved растут, available без изменений.
+  rpc CreditDepositHold(CreditDepositHoldRequest) returns (CreditDepositHoldResponse);
+  // Перевод суммы из резерва в available (админ: HELD → зачислено).
+  rpc ReleaseDepositHold(ReleaseDepositHoldRequest) returns (ReleaseDepositHoldResponse);
+  // Списание из резерва и уменьшение total без возврата в available (блокировка / compliance).
+  rpc ForfeitDepositHold(ForfeitDepositHoldRequest) returns (ForfeitDepositHoldResponse);
   // Создание записи о выводе в учёте (черновик заявки); дальнейшие шаги — резерв, смена статусов, финализация.
   rpc RegisterWithdrawal(RegisterWithdrawalRequest) returns (RegisterWithdrawalResponse);
   // Блокировка (резерв) средств на балансе под конкретный вывод после прохождения проверок.
@@ -58,6 +64,7 @@ message CreditUserBalanceRequest {
   string external_operation_id = 6; // Внешний id операции (custody, провайдер).
   string idempotency_key = 7;      // Ключ идемпотентности вызова.
   optional int32 confirmations = 8;   // Опционально: число подтверждений на момент зачисления.
+  optional int32 log_index = 9;     // Для EVM: индекс лога; для TRON — 0 или не задано.
 }
 
 message CreditUserBalanceResponse {
@@ -68,6 +75,55 @@ message CreditUserBalanceResponse {
   string total = 5;
 }
 
+message CreditDepositHoldRequest {
+  string user_id = 1;
+  string asset = 2;
+  string network = 3;
+  string amount = 4;
+  string tx_hash = 5;
+  string external_operation_id = 6;
+  string idempotency_key = 7;
+  optional int32 confirmations = 8;
+  optional int32 log_index = 9;
+}
+
+message CreditDepositHoldResponse {
+  string deposit_id = 1;
+  string ledger_operation_id = 2;
+  string available = 3;
+  string reserved = 4;
+  string total = 5;
+}
+
+message ReleaseDepositHoldRequest {
+  string user_id = 1;
+  string external_operation_id = 2;
+  string idempotency_key = 3;
+}
+
+message ReleaseDepositHoldResponse {
+  string deposit_id = 1;
+  string ledger_operation_id = 2;
+  string available = 3;
+  string reserved = 4;
+  string total = 5;
+}
+
+message ForfeitDepositHoldRequest {
+  string user_id = 1;
+  string external_operation_id = 2;
+  string idempotency_key = 3;
+  string reason = 4;
+}
+
+message ForfeitDepositHoldResponse {
+  string deposit_id = 1;
+  string ledger_operation_id = 2;
+  string available = 3;
+  string reserved = 4;
+  string total = 5;
+}
+
 message RegisterWithdrawalRequest {
   string user_id = 1;
   string asset = 2;

package/proto/webhook.proto

@@ -1,18 +1,18 @@
 syntax = "proto3";
 
-// Пакет внутреннего gRPC для передачи событий BitGo в mpc_service без публичного HTTP на mpc.
-// Типичный поток: WalletGateway принимает POST /webhooks/bitgo → вызывает ProcessBitGoWebhook с JSON телом.
-// Та же бизнес-логика, что у HTTP-обработчика webhook в mpc (дедуп, обновление транзакций, вызовы Ledger/Notification).
+// Пакет внутреннего gRPC: события BitGo передаются в mpc_service только по gRPC (публичный ingress — Wallet Gateway).
+// Типичный поток: WalletGateway принимает webhook от BitGo → вызывает ProcessBitGoWebhook с JSON-телом в json_payload.
+// Бизнес-логика: дедуп, обновление транзакций, исходящие вызовы в Ledger.
 package webhook.v1;
 
 service WebhookService {
   // Обработка одного события webhook BitGo: разбор JSON, дедупликация по event_id, обновление custody-транзакций,
-  // при необходимости — gRPC в Ledger (статус вывода, зачисление депозита) и уведомления.
+  // при необходимости — gRPC в Ledger (статус вывода, зачисление депозита).
   rpc ProcessBitGoWebhook(ProcessWebhookRequest) returns (ProcessWebhookResponse);
 }
 
 message ProcessWebhookRequest {
-  // Полное тело webhook от BitGo в виде одной JSON-строки (как получено после парсинга HTTP, объекты сериализованы стандартно).
+  // Полное тело события от BitGo в виде одной JSON-строки (как передал gateway после приёма webhook).
   // Клиент (gateway) обязан передавать валидный JSON; mpc парсит и маппит поля transfer / state / data и т.д.
   string json_payload = 1;
 }