unified gateway interface

api/proto/common/gateway/v1/gateway.proto

@@ -26,6 +26,27 @@ enum PaymentMethodType {
   PM_LOCAL_BANK  = 7; // generic local rails, refine later if needed
 }
 
+// Rail identifiers for orchestration. Extend with new rails as needed.
+enum Rail {
+  RAIL_UNSPECIFIED = 0;
+  RAIL_CRYPTO = 1;
+  RAIL_PROVIDER_SETTLEMENT = 2;
+  RAIL_LEDGER = 3;
+  RAIL_CARD_PAYOUT = 4;
+  RAIL_FIAT_ONRAMP = 5;
+}
+
+// Operations supported in a payment plan.
+enum RailOperation {
+  RAIL_OPERATION_UNSPECIFIED = 0;
+  RAIL_OPERATION_DEBIT = 1;
+  RAIL_OPERATION_CREDIT = 2;
+  RAIL_OPERATION_SEND = 3;
+  RAIL_OPERATION_FEE = 4;
+  RAIL_OPERATION_OBSERVE_CONFIRM = 5;
+  RAIL_OPERATION_FX_CONVERT = 6;
+}
+
 // Limits in minor units, e.g. cents
 message AmountLimits {
   int64 min_minor = 1;
@@ -95,3 +116,44 @@ message GatewayDescriptor {
 
   GatewayCapabilities capabilities = 6;
 }
+
+// Capabilities declared per gateway instance for orchestration.
+message RailCapabilities {
+  bool can_pay_in = 1;
+  bool can_pay_out = 2;
+  bool can_read_balance = 3;
+  bool can_send_fee = 4;
+  bool requires_observe_confirm = 5;
+}
+
+message LimitsOverride {
+  string max_volume = 1;
+  string min_amount = 2;
+  string max_amount = 3;
+  string max_fee = 4;
+  int32 max_ops = 5;
+}
+
+// Limits are decimal-safe string amounts unless otherwise noted.
+message Limits {
+  string min_amount = 1;
+  string max_amount = 2;
+  string per_tx_max_fee = 3;
+  string per_tx_min_amount = 4;
+  string per_tx_max_amount = 5;
+  map<string, string> volume_limit = 6; // bucket -> max volume
+  map<string, int32> velocity_limit = 7; // bucket -> max operations count
+  map<string, LimitsOverride> currency_limits = 8;
+}
+
+// A specific gateway instance for a given rail/network pairing.
+message GatewayInstanceDescriptor {
+  string id = 1; // unique instance id
+  Rail rail = 2;
+  string network = 3;
+  repeated string currencies = 4;
+  RailCapabilities capabilities = 5;
+  Limits limits = 6;
+  string version = 7;
+  bool is_enabled = 8;
+}