Fixes + stable gateway ids

api/proto/common/account_role/v1/account_role.proto

@@ -3,17 +3,31 @@ syntax = "proto3";
 package common.account_role.v1;
 option go_package = "github.com/tech/sendico/pkg/proto/common/account_role/v1;accountrolev1";
 
+// AccountRole classifies the purpose of a ledger account within the
+// double-entry accounting model.
 enum AccountRole {
+  // ACCOUNT_ROLE_UNSPECIFIED is the default zero value.
   ACCOUNT_ROLE_UNSPECIFIED = 0;
+  // OPERATING is the main operational account for day-to-day activity.
   OPERATING = 1;
+  // HOLD temporarily locks funds pending settlement or approval.
   HOLD = 2;
+  // TRANSIT is an intermediary account for in-flight transfers.
   TRANSIT = 3;
+  // SETTLEMENT collects funds awaiting final settlement.
   SETTLEMENT = 4;
+  // CLEARING is used during reconciliation and netting cycles.
   CLEARING = 5;
+  // PENDING tracks amounts that are authorised but not yet captured.
   PENDING = 6;
+  // RESERVE holds funds set aside as collateral or buffer.
   RESERVE = 7;
+  // LIQUIDITY pools funds available for outgoing payments.
   LIQUIDITY = 8;
+  // FEE accumulates collected fee revenue.
   FEE = 9;
+  // CHARGEBACK records reversed or disputed amounts.
   CHARGEBACK = 10;
+  // ADJUSTMENT captures manual or system-initiated balance corrections.
   ADJUSTMENT = 11;
 }

api/proto/common/archivable/v1/archivable.proto

@@ -4,8 +4,8 @@ package common.archivable.v1;
 
 option go_package = "github.com/tech/sendico/pkg/proto/common/archivable/v1;archivablev1";
 
-
-
+// Archivable is an embeddable fragment that marks a record as soft-deleted.
 message Archivable {
+  // is_archived is true when the record has been logically removed.
   bool is_archived = 1;
-}
+}

api/proto/common/fx/v1/fx.proto

@@ -2,13 +2,20 @@ syntax = "proto3";
 package common.fx.v1;
 option go_package = "github.com/tech/sendico/pkg/proto/common/fx/v1;fxv1";
 
+// CurrencyPair identifies a foreign-exchange pair (e.g. EUR/USD).
 message CurrencyPair {
+  // base is the base currency code (ISO 4217).
   string base  = 1;
+  // quote is the quote (counter) currency code (ISO 4217).
   string quote = 2;
 }
 
+// Side indicates the direction of an FX conversion relative to the pair.
 enum Side {
+  // SIDE_UNSPECIFIED is the default zero value.
   SIDE_UNSPECIFIED        = 0;
+  // BUY_BASE_SELL_QUOTE buys the base currency, selling the quote currency.
   BUY_BASE_SELL_QUOTE     = 1;
+  // SELL_BASE_BUY_QUOTE sells the base currency, buying the quote currency.
   SELL_BASE_BUY_QUOTE     = 2;
 }

api/proto/common/money/v1/money.proto

@@ -2,22 +2,39 @@ syntax = "proto3";
 package common.money.v1;
 option go_package = "github.com/tech/sendico/pkg/proto/common/money/v1;moneyv1";
 
-message Decimal { string value = 1; } // exact decimal as string
-
-message Money {
-  string amount   = 1; // decimal string
-  string currency = 2; // ISO 4217 or your code set
+// Decimal represents an exact decimal value encoded as a string to avoid
+// floating-point precision loss.
+message Decimal {
+  // value is the decimal string representation (e.g. "123.45").
+  string value = 1;
 }
 
+// Money pairs a decimal amount with a currency code.
+message Money {
+  // amount is the decimal string representation.
+  string amount   = 1;
+  // currency is the ISO 4217 currency code (e.g. "USD", "EUR").
+  string currency = 2;
+}
+
+// RoundingMode specifies how to round monetary calculations.
 enum RoundingMode {
+  // ROUNDING_MODE_UNSPECIFIED is the default zero value.
   ROUNDING_MODE_UNSPECIFIED = 0;
+  // ROUND_HALF_EVEN rounds to the nearest even digit (banker's rounding).
   ROUND_HALF_EVEN = 1;
+  // ROUND_HALF_UP rounds halves away from zero.
   ROUND_HALF_UP   = 2;
+  // ROUND_DOWN truncates towards zero.
   ROUND_DOWN      = 3;
 }
 
+// CurrencyMeta describes the precision and rounding rules for a currency.
 message CurrencyMeta {
+  // code is the ISO 4217 currency code.
   string code = 1;
+  // decimals is the number of minor-unit digits (e.g. 2 for USD, 0 for JPY).
   uint32 decimals = 2;
+  // rounding is the preferred rounding mode for this currency.
   RoundingMode rounding = 3;
 }

api/proto/common/organization_bound/v1/obound.proto

@@ -4,7 +4,9 @@ package common.obound.v1;
 
 option go_package = "github.com/tech/sendico/pkg/proto/common/organization_bound/v1;oboundv1";
 
-
+// OrganizationBound is an embeddable fragment that ties a record to an
+// organisation for multi-tenancy isolation.
 message OrganizationBound {
+  // organization_ref is the unique identifier of the owning organisation.
   string organization_ref = 1;
-}
+}

api/proto/common/pagination/v1/cursor.proto

@@ -2,11 +2,17 @@ syntax = "proto3";
 package common.pagination.v1;
 option go_package = "github.com/tech/sendico/pkg/proto/common/pagination/v1;paginationv1";
 
+// CursorPageRequest carries opaque cursor-based pagination parameters.
 message CursorPageRequest {
-  string cursor = 1; // opaque
-  int32  limit  = 2; // page size
+  // cursor is the opaque continuation token from a previous response.
+  string cursor = 1;
+  // limit is the maximum number of items to return per page.
+  int32  limit  = 2;
 }
 
+// CursorPageResponse carries the opaque token for the next page.
 message CursorPageResponse {
-  string next_cursor = 1; // opaque
+  // next_cursor is the opaque token to fetch the next page; empty when no
+  // more results are available.
+  string next_cursor = 1;
 }

api/proto/common/pagination/v2/cursor.proto

@@ -2,11 +2,14 @@ syntax = "proto3";
 package common.pagination.v2;
 option go_package = "github.com/tech/sendico/pkg/proto/common/pagination/v2;paginationv2";
 
-
 import "google/protobuf/wrappers.proto";
 
+// ViewCursor provides offset-based pagination with an optional archive filter.
 message ViewCursor {
+  // limit is the maximum number of items to return.
   google.protobuf.Int64Value limit = 1;
+  // offset is the zero-based starting position in the result set.
   google.protobuf.Int64Value offset = 2;
+  // is_archived, when set, filters results by their archived status.
   google.protobuf.BoolValue is_archived = 3;
 }

api/proto/common/payment/v1/asset.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+
+package common.payment.v1;
+
+option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
+
+// ChainAssetKey identifies an on-chain asset by network and token symbol.
+message ChainAssetKey {
+  string chain = 1;
+  string token_symbol = 2;
+}
+
+// ChainAsset extends ChainAssetKey with optional contract address override.
+message ChainAsset {
+  ChainAssetKey key = 1;
+  optional string contract_address = 2;
+}
+

api/proto/common/permission_bound/v1/pbound.proto

@@ -8,10 +8,15 @@ import "api/proto/common/storable/v1/storable.proto";
 import "api/proto/common/archivable/v1/archivable.proto";
 import "api/proto/common/organization_bound/v1/obound.proto";
 
-
+// PermissionBound bundles persistence metadata, soft-delete state,
+// organisation ownership, and an RBAC permission reference.
 message PermissionBound {
+  // storable carries the record's persistence metadata.
   common.storable.v1.Storable storable = 1;
+  // archivable carries the soft-delete flag.
   common.archivable.v1.Archivable archivable = 2;
+  // organization_bound ties the record to an organisation.
   common.obound.v1.OrganizationBound organization_bound = 3;
+  // permission_ref is the RBAC permission identifier that governs access.
   string permission_ref = 4;
-}
+}

api/proto/common/trace/v1/trace.proto

@@ -2,8 +2,12 @@ syntax = "proto3";
 package common.trace.v1;
 option go_package = "github.com/tech/sendico/pkg/proto/common/trace/v1;tracev1";
 
+// TraceContext carries cross-service request correlation identifiers.
 message TraceContext {
+  // request_ref is the unique identifier for this individual request.
   string request_ref     = 1;
+  // idempotency_key prevents duplicate processing of the same operation.
   string idempotency_key = 2;
+  // trace_ref groups related requests within a single logical flow.
   string trace_ref       = 3;
 }

api/proto/payments/quotation/v2/interface.proto

@@ -7,21 +7,17 @@ option go_package = "github.com/tech/sendico/pkg/proto/payments/quotation/v2;quo
 import "google/protobuf/timestamp.proto";
 import "api/proto/common/storable/v1/storable.proto";
 import "api/proto/common/money/v1/money.proto";
+import "api/proto/common/payment/v1/asset.proto";
 import "api/proto/billing/fees/v1/fees.proto";
 import "api/proto/oracle/v1/oracle.proto";
 
-enum QuoteKind {
-  QUOTE_KIND_UNSPECIFIED = 0;
+enum QuoteState {
+  QUOTE_STATE_UNSPECIFIED = 0;
 
-  QUOTE_KIND_EXECUTABLE = 1; // can be executed now (subject to execution-time checks)
-  QUOTE_KIND_INDICATIVE = 2; // informational only
-}
-
-enum QuoteLifecycle {
-  QUOTE_LIFECYCLE_UNSPECIFIED = 0;
-
-  QUOTE_LIFECYCLE_ACTIVE = 1;
-  QUOTE_LIFECYCLE_EXPIRED = 2;
+  QUOTE_STATE_INDICATIVE = 1;
+  QUOTE_STATE_EXECUTABLE = 2;
+  QUOTE_STATE_BLOCKED = 3;
+  QUOTE_STATE_EXPIRED = 4;
 }
 
 enum QuoteBlockReason {
@@ -59,18 +55,25 @@ message RouteHop {
   RouteHopRole role = 6;
 }
 
+message RouteSettlement {
+  common.payment.v1.ChainAsset asset = 1;
+  string model = 2;
+}
+
 // Abstract execution route selected during quotation.
 // This is not an execution plan and must not contain operational steps.
 message RouteSpecification {
+  // Optional summary fields. Topology is represented by hops + route_ref.
   string rail = 1;
   string provider = 2;
   string payout_method = 3;
-  string settlement_asset = 4;
-  string settlement_model = 5;
+  reserved 4, 5;
+  reserved "settlement_asset", "settlement_model";
   string network = 6;
   string route_ref = 7;
   string pricing_profile_ref = 8;
   repeated RouteHop hops = 9;
+  RouteSettlement settlement = 10;
 }
 
 // Execution assumptions and constraints evaluated at quotation time.
@@ -87,17 +90,10 @@ message ExecutionConditions {
 
 message PaymentQuote {
   common.storable.v1.Storable storable = 1;
-  QuoteKind kind = 2;
-  QuoteLifecycle lifecycle = 3;
-
-  // Execution-status rules:
-  // 1) kind=QUOTE_KIND_INDICATIVE => execution_status must be unset.
-  // 2) lifecycle=QUOTE_LIFECYCLE_EXPIRED => execution_status must be unset.
-  // 3) kind=QUOTE_KIND_EXECUTABLE and lifecycle=QUOTE_LIFECYCLE_ACTIVE => execution_status must be set.
-  oneof execution_status {
-    bool executable = 13; // must be true when set
-    QuoteBlockReason block_reason = 4;
-  }
+  QuoteState state = 2;
+  QuoteBlockReason block_reason = 4;
+  reserved 3, 13;
+  reserved "kind", "lifecycle", "executable";
 
   common.money.v1.Money debit_amount = 5;
   common.money.v1.Money credit_amount = 6;