refactored notificatoin / tgsettle responsibility boundaries

api/proto/payments/shared/v1/shared.proto

@@ -14,6 +14,7 @@ import "api/proto/billing/fees/v1/fees.proto";
 import "api/proto/gateway/chain/v1/chain.proto";
 import "api/proto/oracle/v1/oracle.proto";
 
+// PaymentKind classifies the type of payment operation.
 enum PaymentKind {
   PAYMENT_KIND_UNSPECIFIED = 0;
   PAYMENT_KIND_PAYOUT = 1;
@@ -21,6 +22,7 @@ enum PaymentKind {
   PAYMENT_KIND_FX_CONVERSION = 3;
 }
 
+// PaymentState tracks the lifecycle of a payment.
 enum PaymentState {
   PAYMENT_STATE_UNSPECIFIED = 0;
   PAYMENT_STATE_ACCEPTED = 1;
@@ -31,6 +33,7 @@ enum PaymentState {
   PAYMENT_STATE_CANCELLED = 6;
 }
 
+// PaymentFailureCode categorises the reason for a payment failure.
 enum PaymentFailureCode {
   FAILURE_UNSPECIFIED = 0;
   FAILURE_BALANCE = 1;
@@ -41,21 +44,26 @@ enum PaymentFailureCode {
   FAILURE_POLICY = 6;
 }
 
+// RequestMeta carries organisation context and tracing information for
+// every payment service request.
 message RequestMeta {
   string organization_ref = 1;
   common.trace.v1.TraceContext trace = 2;
 }
 
+// LedgerEndpoint identifies a source or destination on the internal ledger.
 message LedgerEndpoint {
   string ledger_account_ref = 1;
   string contra_ledger_account_ref = 2;
 }
 
+// ManagedWalletEndpoint identifies a platform-managed blockchain wallet.
 message ManagedWalletEndpoint {
   string managed_wallet_ref = 1;
   chain.gateway.v1.Asset asset = 2;
 }
 
+// ExternalChainEndpoint identifies an external blockchain address.
 message ExternalChainEndpoint {
   chain.gateway.v1.Asset asset = 1;
   string address = 2;
@@ -76,6 +84,7 @@ message CardEndpoint {
   string masked_pan = 8;
 }
 
+// PaymentEndpoint is a polymorphic endpoint that can target any supported rail.
 message PaymentEndpoint {
   oneof endpoint {
     LedgerEndpoint ledger = 1;
@@ -87,6 +96,7 @@ message PaymentEndpoint {
   string instance_id = 11;
 }
 
+// FXIntent describes the foreign-exchange requirements for a payment.
 message FXIntent {
   common.fx.v1.CurrencyPair pair = 1;
   common.fx.v1.Side side = 2;
@@ -96,6 +106,8 @@ message FXIntent {
   int32 max_age_ms = 6;
 }
 
+// PaymentIntent fully describes a payment to be executed, including source,
+// destination, amount, FX, fee policy, and settlement preferences.
 message PaymentIntent {
   PaymentKind kind = 1;
   PaymentEndpoint source = 2;
@@ -111,6 +123,8 @@ message PaymentIntent {
   string ref = 12;
 }
 
+// Customer holds payer identity and address details for compliance and
+// routing purposes.
 message Customer {
   string id = 1;
   string first_name = 2;
@@ -124,6 +138,8 @@ message Customer {
   string address = 10;
 }
 
+// PaymentQuote captures the pricing snapshot for a payment including
+// debit amount, expected settlement, fees, and FX details.
 message PaymentQuote {
   common.money.v1.Money debit_amount = 1;
   common.money.v1.Money expected_settlement_amount = 2;
@@ -136,6 +152,7 @@ message PaymentQuote {
   common.money.v1.Money debit_settlement_amount = 9;
 }
 
+// PaymentQuoteAggregate summarises totals across multiple payment quotes.
 message PaymentQuoteAggregate {
   repeated common.money.v1.Money debit_amounts = 1;
   repeated common.money.v1.Money expected_settlement_amounts = 2;
@@ -143,6 +160,8 @@ message PaymentQuoteAggregate {
   repeated common.money.v1.Money network_fee_totals = 4;
 }
 
+// ExecutionRefs collects cross-service references created during payment
+// execution (ledger entries, chain transfers, card payouts).
 message ExecutionRefs {
   string debit_entry_ref = 1;
   string credit_entry_ref = 2;
@@ -152,6 +171,7 @@ message ExecutionRefs {
   string fee_transfer_ref = 6;
 }
 
+// ExecutionStep describes a single operational step in the legacy execution plan.
 message ExecutionStep {
   string code = 1;
   string description = 2;
@@ -164,11 +184,13 @@ message ExecutionStep {
   string operation_ref = 9;
 }
 
+// ExecutionPlan is the legacy ordered list of steps for fulfilling a payment.
 message ExecutionPlan {
   repeated ExecutionStep steps = 1;
   common.money.v1.Money total_network_fee = 2;
 }
 
+// PaymentStep is a single rail-level operation within a PaymentPlan.
 message PaymentStep {
   common.gateway.v1.Rail rail = 1;
   string gateway_id = 2; // required for external rails
@@ -181,6 +203,8 @@ message PaymentStep {
   repeated string commit_after = 9;
 }
 
+// PaymentPlan is the orchestrated sequence of rail-level steps that fulfil
+// a payment, including FX and fee lines.
 message PaymentPlan {
   string id = 1;
   repeated PaymentStep steps = 2;
@@ -202,6 +226,8 @@ message CardPayout {
   string gateway_reference = 8;
 }
 
+// Payment is the top-level aggregate representing a payment throughout its
+// lifecycle, from initiation through settlement or failure.
 message Payment {
   string payment_ref = 1;
   string idempotency_key = 2;