feat: add settlement dismissal and cancellation RPCs

auth/v1/internal_srv.proto

@@ -6,6 +6,7 @@ import "auth/v1/msg.proto";
 import "base/v1/msg.proto";
 
 service InternalAuthorizationService {
+  rpc GetUserAnalytics(base.v1.Empty) returns (UserAnalytics);
   rpc InternalAuthorizationSrvHealth(base.v1.Empty) returns (base.v1.StatusRes);
   rpc LookUpName(LookUpNameReq) returns (LookUpNameRes) {}
   // This meant to only be used in a worker process
@@ -21,3 +22,8 @@ service InternalAuthorizationService {
   rpc AssignRoleToUser(AssignRoleToUserReq) returns (InternalIAM) {}
   rpc AssignPermissionToUser(AssignPermissionToUserReq) returns (InternalIAM) {}
 }
+
+message UserAnalytics {
+  int64 user_count = 1;
+  map<string, int64> user_count_by_kyc_level = 2;
+}

ledger/v1/msg.proto

@@ -4,6 +4,43 @@ package ledger.v1;
 
 import "google/protobuf/timestamp.proto";
 
+message OperatingModeResponse {
+  // NORMAL or GL_ONLY. No automatic outage failover.
+  string mode = 1;
+  int64 revision = 2;
+  string actor_id = 3;
+  string reason = 4;
+  google.protobuf.Timestamp changed_at = 5;
+}
+
+message SetOperatingModeRequest {
+  string mode = 1;
+  int64 expected_revision = 2;
+  string actor_id = 3;
+  string reason = 4;
+  // Required when returning from GL_ONLY to NORMAL.
+  bool reconciliation_confirmed = 5;
+}
+
+message GetUserBalancesRequest {
+  string owner_type = 1;
+  string owner_id = 2;
+  optional int64 asset_id = 3;
+}
+
+message UserAssetBalance {
+  int64 asset_id = 1;
+  string available = 2;
+  string frozen = 3;
+  string total = 4;
+}
+
+message GetUserBalancesResponse {
+  string owner_type = 1;
+  string owner_id = 2;
+  repeated UserAssetBalance balances = 3;
+}
+
 enum AccountClass {
   ACCOUNT_CLASS_UNSPECIFIED = 0;
   ACCOUNT_CLASS_USER_AVAILABLE = 1;
@@ -216,3 +253,13 @@ message RetrySettlementRequest {
 message RetrySettlementResponse {
   Settlement settlement = 1;
 }
+
+message IgnoreSettlementRequest {
+  string settlement_id = 1;
+  string actor_id = 2;
+  string reason = 3;
+}
+
+message IgnoreSettlementResponse {
+  Settlement settlement = 1;
+}

ledger/v1/srv.proto

@@ -6,6 +6,12 @@ import "base/v1/msg.proto";
 import "ledger/v1/msg.proto";
 
 service GeneralLedgerService {
+  rpc GetOperatingMode(base.v1.Empty) returns (OperatingModeResponse);
+  // Operator-only; requires x-admin-token and an optimistic revision.
+  rpc SetOperatingMode(SetOperatingModeRequest) returns (OperatingModeResponse);
+  // Trusted internal execution; requires x-admin-token and GL_ONLY mode.
+  rpc PostInternalJournal(AppendJournalRequest) returns (AppendJournalResponse);
+  rpc GetUserBalances(GetUserBalancesRequest) returns (GetUserBalancesResponse);
   rpc Health(base.v1.Empty) returns (HealthResponse);
   rpc AppendJournal(AppendJournalRequest) returns (AppendJournalResponse);
   rpc AppendTransactionEvent(AppendTransactionEventRequest) returns (AppendTransactionEventResponse);
@@ -17,4 +23,7 @@ service GeneralLedgerService {
   rpc GetSettlement(GetSettlementRequest) returns (Settlement);
   // Restricted operator command. Requires the configured x-admin-token metadata.
   rpc RetrySettlement(RetrySettlementRequest) returns (RetrySettlementResponse);
+  // Operator-reviewed, terminal dismissal. Does not confirm or reverse payment.
+  // Requires x-admin-token and a recorded reason; only unlocked failed settlements.
+  rpc IgnoreSettlement(IgnoreSettlementRequest) returns (IgnoreSettlementResponse);
 }

market/v1/msg.proto

@@ -72,6 +72,8 @@ message MarketOrder {
   repeated string comment = 21;
   optional MarketOrder source = 22; // purchase is done via this field
   bool is_ico = 23;
+  optional string starts_at = 24; // RFC3339; absent means immediately available
+  optional string ends_at = 25; // RFC3339; absent means no scheduled end
   // repeated string attachments = 14; // possible files included by
   // seller/buyer
 }
@@ -113,6 +115,15 @@ message MarketOrderList {
   uint32 total_count = 4;
 }
 
+// AdminCancelOrderReq is used by trusted administrative tooling to cancel an
+// order through the wallet service.  The wallet service authenticates the
+// caller with the administrative gRPC token; actor_user_id is retained for
+// audit attribution.
+message AdminCancelOrderReq {
+  uint64 order_id = 1;
+  int64 actor_user_id = 2;
+}
+
 /*
  * participant_type: IS Maker/Taker
  * side: IS Buying/Selling
@@ -132,6 +143,8 @@ message NewMarketReq {
   // TODO: maker market order as optional
   optional uint64 maker_order_id = 9;
   bool is_ico = 10;
+  optional string starts_at = 11; // RFC3339
+  optional string ends_at = 12; // RFC3339
 }
 
 enum MarketOrdersSortBy {

market/v1/srv.proto

@@ -20,6 +20,8 @@ service MarketplaceSrv {
   rpc CalcICOBuy(wallet.v1.BuyAssetReq) returns (wallet.v1.CalcBuyAssetRes);
 
   rpc CancelOrder(auth.v1.IdReqWithIAMAndTFA) returns (base.v1.StatusRes); // cancel an order
+  rpc AdminCancelOrder(AdminCancelOrderReq) returns (base.v1.StatusRes); // cancel an order from trusted admin tooling
+  rpc DeleteOrder(auth.v1.IdReqWithIAMAndTFA) returns (base.v1.StatusRes); // delete a closed order
 
   rpc NewMarketOrder(NewMarketReq) returns (MarketOrder); // insert new buy order to market
   rpc GenerateMarketContract(MarketContractReq) returns (ContractMarketRes);

wallet/v1/internal_srv.proto

@@ -29,4 +29,15 @@ service InternalWalletSrv {
   // deactivation/locking so referenced financial history remains intact.
   rpc AdminUpsertAsset(AdminUpsertAssetReq) returns (AdminAssetMutationRes);
   rpc AdminDeactivateAsset(AdminDeactivateAssetReq) returns (base.v1.StatusRes);
+
+  rpc AdminApproveIRTWithdrawal(AdminApproveIRTWithdrawalReq) returns (base.v1.StatusRes);
+  // Cancels an unapproved request and releases its reservation atomically.
+  rpc AdminCancelIRTWithdrawal(AdminCancelIRTWithdrawalReq) returns (base.v1.StatusRes);
+  // Cancel only an undecided ICO agreement, atomically against user acceptance.
+  rpc AdminCancelICOAgreement(AdminCancelICOAgreementReq) returns (base.v1.StatusRes);
+
+  // Bank statement receipts are checked and confirmed through the wallet owner.
+  // Confirmation is idempotent by bank_transaction_number.
+  rpc AdminCheckBankDeposit(AdminBankDepositReq) returns (AdminBankDepositRes);
+  rpc AdminConfirmBankDeposit(AdminBankDepositReq) returns (AdminBankDepositRes);
 }

wallet/v1/msg.proto

@@ -227,6 +227,33 @@ message LockAssetReq {
   optional auth.v1.TFA tfa = 4; // if request is not internal
 }
 
+// Administrative approval is the only transition that may enqueue an IRT
+// withdrawal for blockchain settlement. The receipt identifies the completed
+// off-chain bank payment.
+message AdminApproveIRTWithdrawalReq {
+  uint64 withdraw_log_id = 1;
+  string bank_receipt = 2;
+  int64 actor_user_id = 3;
+}
+
+message AdminBankDepositReq {
+  string bank_transaction_number = 1;
+  string depositor_id = 2; // ten-digit national ID followed by the two-digit checksum
+  int64 amount_rial = 3;
+  string paid_at = 4; // RFC3339
+  int64 user_id = 5; // wallet verifies this user's national ID against depositor_id
+  int64 actor_user_id = 6;
+}
+
+message AdminBankDepositRes {
+  int64 user_id = 1;
+  string national_id = 2;
+  int64 transaction_id = 3; // zero until confirmed
+  bool already_registered = 4;
+  string amount_irt = 5; // exact decimal amount
+  string status = 6;
+}
+
 /*
    BNPL - not really but close name
 */
@@ -871,3 +898,15 @@ message AdminDeactivateAssetReq {
 message AdminAssetMutationRes {
   int64 asset_id = 1;
 }
+
+// Administrative cancellation never changes a decided agreement or moves funds.
+message AdminCancelICOAgreementReq {
+  uint64 agreement_id = 1;
+  int64 actor_user_id = 2;
+}
+
+message AdminCancelIRTWithdrawalReq {
+  uint64 withdraw_log_id = 1;
+  string reason = 2;
+  int64 actor_user_id = 3;
+}

wallet/v1/srv.proto

@@ -7,6 +7,7 @@ import "base/v1/msg.proto";
 import "wallet/v1/msg.proto";
 
 service WalletService {
+  rpc GetWalletAnalytics(base.v1.Empty) returns (WalletAnalytics);
   rpc WalletSrvHealth(base.v1.Empty) returns (base.v1.StatusRes);
 
   rpc GetNetworkList(base.v1.Empty) returns (NetworkList);
@@ -68,3 +69,10 @@ service WalletService {
   rpc DeclineBuyContract(DeclineBuyContractReq) returns (base.v1.StatusRes);
   // rpc GenerateMarketContract(MarketContractReq) returns (ContractRes);
 }
+
+message WalletAnalytics {
+  int64 transaction_count = 1;
+  map<string, int64> transaction_count_by_type = 2;
+  int64 account_count = 3;
+  int64 project_count = 4;
+}