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;
 }