feat: deprecate Currency enum and migrate to string instrument_code (#1222)

* feat: deprecate Currency enum and migrate to string instrument_code

Replaces the Currency protobuf enum with string instrument_code fields
across all affected protos and Go service code. This supports the
Universal Asset System which handles currencies, energy (kWh), carbon
credits, GPU hours, and other instruments beyond ISO 4217 currencies.

Proto changes:
- Mark Currency enum as deprecated in common/v1/types.proto
- Replace Currency enum fields with string instrument_code in:
  - events/v1/current_account_events.proto (base_currency → base_instrument_code)
  - events/v1/deposit_event.proto (currency → instrument_code)
  - events/v1/financial_accounting_events.proto (base_currency → base_instrument_code)
  - events/v1/position_keeping_events.proto (currency → instrument_code, two messages)
  - financial_accounting/v1/financial_accounting.proto (base_currency → base_instrument_code)
- Add breaking change ignores to buf.yaml for intentional field changes

Go changes:
- Remove currencyToProto() from position-keeping/domain/events.go
- Remove fromProtoCurrency()/toProtoCurrency() from financial-accounting/service/adapters.go
- Remove convertCurrencyToISO() from financial-accounting/adapters/messaging/deposit_consumer.go
- Remove Currency enum usage from payment-order service (use string codes directly)
- Remove Currency enum usage from current-account saga_handlers.go
- Mark DomainCurrencyToProto/CurrencyCodeToProto in mappers/currency.go as deprecated
- Update all tests to use string instrument codes instead of enum values

* fix: address CodeRabbit review comments on test quality

- Fix stale error message "BaseCurrency mismatch" → "BaseInstrumentCode mismatch"
  in financial_accounting_events_test.go
- Replace tautological placeholder assertion in TestPostLedgerEntries_UnsupportedCurrency
  with meaningful tests showing unsupported currencies are rejected at domain.NewMoney
  call site (validation moved from PostLedgerEntries to Money construction)

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

api/proto/buf.yaml

@@ -3,3 +3,47 @@ deps:
   - buf.build/bufbuild/protovalidate
   - buf.build/googleapis/googleapis
   - buf.build/grpc-ecosystem/grpc-gateway
+
+breaking:
+  # Intentional breaking changes for asset-agnostic-accounts epic:
+  # Replacing deprecated Currency enum fields with string instrument_code fields.
+  # These fields changed from enum to string type and were renamed to reflect
+  # the Universal Asset System (supporting currencies, energy, carbon credits, etc.).
+  # Ignoring specific rules to allow these deliberate proto evolution decisions.
+  ignore_only:
+    FIELD_SAME_JSON_NAME:
+      - meridian/events/v1/current_account_events.proto
+      - meridian/events/v1/deposit_event.proto
+      - meridian/events/v1/financial_accounting_events.proto
+      - meridian/events/v1/position_keeping_events.proto
+      - meridian/financial_accounting/v1/financial_accounting.proto
+    FIELD_SAME_TYPE:
+      - meridian/events/v1/current_account_events.proto
+      - meridian/events/v1/deposit_event.proto
+      - meridian/events/v1/financial_accounting_events.proto
+      - meridian/events/v1/position_keeping_events.proto
+      - meridian/financial_accounting/v1/financial_accounting.proto
+    FIELD_SAME_ONEOF:
+      - meridian/events/v1/current_account_events.proto
+      - meridian/events/v1/deposit_event.proto
+      - meridian/events/v1/financial_accounting_events.proto
+      - meridian/events/v1/position_keeping_events.proto
+      - meridian/financial_accounting/v1/financial_accounting.proto
+    FIELD_SAME_NAME:
+      - meridian/events/v1/current_account_events.proto
+      - meridian/events/v1/deposit_event.proto
+      - meridian/events/v1/financial_accounting_events.proto
+      - meridian/events/v1/position_keeping_events.proto
+      - meridian/financial_accounting/v1/financial_accounting.proto
+    FIELD_WIRE_COMPATIBLE_TYPE:
+      - meridian/events/v1/current_account_events.proto
+      - meridian/events/v1/deposit_event.proto
+      - meridian/events/v1/financial_accounting_events.proto
+      - meridian/events/v1/position_keeping_events.proto
+      - meridian/financial_accounting/v1/financial_accounting.proto
+    FIELD_WIRE_JSON_COMPATIBLE_TYPE:
+      - meridian/events/v1/current_account_events.proto
+      - meridian/events/v1/deposit_event.proto
+      - meridian/events/v1/financial_accounting_events.proto
+      - meridian/events/v1/position_keeping_events.proto
+      - meridian/financial_accounting/v1/financial_accounting.proto

api/proto/meridian/common/v1/types.proto

@@ -34,22 +34,37 @@ enum TransactionStatus {
 }
 
 // Currency defines ISO 4217 currency codes commonly used in banking.
+//
+// Deprecated: Use string instrument_code fields instead. This enum is retained
+// for backward compatibility with existing serialized messages and will be
+// removed in a future version. New fields should use string instrument_code
+// (e.g., "GBP", "USD", "EUR") which supports the Universal Asset System
+// for non-currency instruments such as energy (kWh) and carbon credits.
 enum Currency {
+  option deprecated = true;
+
   // CURRENCY_UNSPECIFIED means the currency is unknown.
   CURRENCY_UNSPECIFIED = 0;
   // CURRENCY_GBP is British Pound Sterling.
+  // Deprecated: Use instrument_code = "GBP" instead.
   CURRENCY_GBP = 1;
   // CURRENCY_USD is United States Dollar.
+  // Deprecated: Use instrument_code = "USD" instead.
   CURRENCY_USD = 2;
   // CURRENCY_EUR is Euro.
+  // Deprecated: Use instrument_code = "EUR" instead.
   CURRENCY_EUR = 3;
   // CURRENCY_JPY is Japanese Yen.
+  // Deprecated: Use instrument_code = "JPY" instead.
   CURRENCY_JPY = 4;
   // CURRENCY_CHF is Swiss Franc.
+  // Deprecated: Use instrument_code = "CHF" instead.
   CURRENCY_CHF = 5;
   // CURRENCY_CAD is Canadian Dollar.
+  // Deprecated: Use instrument_code = "CAD" instead.
   CURRENCY_CAD = 6;
   // CURRENCY_AUD is Australian Dollar.
+  // Deprecated: Use instrument_code = "AUD" instead.
   CURRENCY_AUD = 7;
 }
 

api/proto/meridian/events/v1/current_account_events.proto

@@ -31,10 +31,11 @@ message AccountCreatedEvent {
     max_len: 34  // IBAN max length
   }];
 
-  // base_currency is the account's base currency
-  meridian.common.v1.Currency base_currency = 4 [(buf.validate.field).enum = {
-    defined_only: true
-    not_in: [0]
+  // base_instrument_code is the account's base instrument code (e.g., "GBP", "USD").
+  // Replaces the deprecated base_currency enum field.
+  string base_instrument_code = 4 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 50
   }];
 
   // account_status is the initial status (typically ACTIVE)

api/proto/meridian/events/v1/deposit_event.proto

@@ -4,7 +4,6 @@ package meridian.events.v1;
 
 import "buf/validate/validate.proto";
 import "google/protobuf/timestamp.proto";
-import "meridian/common/v1/types.proto";
 
 option go_package = "github.com/meridianhub/meridian/api/proto/meridian/events/v1;eventsv1";
 
@@ -22,10 +21,11 @@ message DepositEvent {
   // amount_cents is the deposit amount in cents (or smallest currency unit)
   int64 amount_cents = 2 [(buf.validate.field).int64 = {gt: 0}];
 
-  // currency is the ISO 4217 currency code
-  meridian.common.v1.Currency currency = 3 [(buf.validate.field).enum = {
-    defined_only: true
-    not_in: [0]
+  // instrument_code is the ISO 4217 currency code or other instrument identifier (e.g., "GBP", "USD").
+  // Replaces the deprecated currency enum field.
+  string instrument_code = 3 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 50
   }];
 
   // correlation_id links this event to the originating transaction

api/proto/meridian/events/v1/financial_accounting_events.proto

@@ -34,10 +34,11 @@ message FinancialBookingLogInitiatedEvent {
     max_len: 255
   }];
 
-  // base_currency is the currency for this booking log
-  meridian.common.v1.Currency base_currency = 5 [(buf.validate.field).enum = {
-    defined_only: true
-    not_in: [0]
+  // base_instrument_code is the instrument code for this booking log (e.g., "GBP", "USD", "kWh").
+  // Replaces the deprecated base_currency enum field.
+  string base_instrument_code = 5 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 50
   }];
 
   // correlation_id links related events across services

api/proto/meridian/events/v1/financial_accounting_events_test.go

@@ -17,7 +17,7 @@ func TestFinancialBookingLogInitiatedEvent_Serialization(t *testing.T) {
 		FinancialAccountType:    "DEBIT",
 		ProductServiceReference: "product-456",
 		BusinessUnitReference:   "bu-789",
-		BaseCurrency:            commonv1.Currency_CURRENCY_GBP,
+		BaseInstrumentCode:      "GBP",
 		CorrelationId:           "correlation-abc",
 		CausationId:             "causation-def",
 		Timestamp:               timestamppb.New(time.Now()),
@@ -43,8 +43,8 @@ func TestFinancialBookingLogInitiatedEvent_Serialization(t *testing.T) {
 	if decoded.FinancialAccountType != event.FinancialAccountType {
 		t.Errorf("FinancialAccountType mismatch: got %v, want %v", decoded.FinancialAccountType, event.FinancialAccountType)
 	}
-	if decoded.BaseCurrency != event.BaseCurrency {
-		t.Errorf("BaseCurrency mismatch: got %v, want %v", decoded.BaseCurrency, event.BaseCurrency)
+	if decoded.BaseInstrumentCode != event.BaseInstrumentCode {
+		t.Errorf("BaseInstrumentCode mismatch: got %v, want %v", decoded.BaseInstrumentCode, event.BaseInstrumentCode)
 	}
 	if decoded.Version != event.Version {
 		t.Errorf("Version mismatch: got %v, want %v", decoded.Version, event.Version)
@@ -311,7 +311,7 @@ func TestFinancialBookingLogInitiatedEvent_EmptyFields(t *testing.T) {
 		FinancialAccountType:    "DEBIT",
 		ProductServiceReference: "",
 		BusinessUnitReference:   "",
-		BaseCurrency:            commonv1.Currency_CURRENCY_GBP,
+		BaseInstrumentCode:      "GBP",
 		CorrelationId:           "",
 		CausationId:             "",
 		Timestamp:               timestamppb.New(time.Now()),
@@ -345,7 +345,7 @@ func TestFinancialBookingLogInitiatedEvent_MaxLengthFields(t *testing.T) {
 		FinancialAccountType:    "DEBIT",
 		ProductServiceReference: maxLengthString,
 		BusinessUnitReference:   maxLengthString,
-		BaseCurrency:            commonv1.Currency_CURRENCY_GBP,
+		BaseInstrumentCode:      "GBP",
 		CorrelationId:           maxLengthString,
 		CausationId:             maxLengthString,
 		Timestamp:               timestamppb.New(time.Now()),
@@ -374,7 +374,7 @@ func TestFinancialBookingLogInitiatedEvent_UnspecifiedEnum(t *testing.T) {
 		FinancialAccountType:    "",
 		ProductServiceReference: "product-456",
 		BusinessUnitReference:   "bu-789",
-		BaseCurrency:            commonv1.Currency_CURRENCY_UNSPECIFIED,
+		BaseInstrumentCode:      "",
 		CorrelationId:           "correlation-abc",
 		CausationId:             "causation-def",
 		Timestamp:               timestamppb.New(time.Now()),
@@ -394,8 +394,8 @@ func TestFinancialBookingLogInitiatedEvent_UnspecifiedEnum(t *testing.T) {
 	if decoded.FinancialAccountType != "" {
 		t.Errorf("Expected ACCOUNT_TYPE_UNSPECIFIED, got %v", decoded.FinancialAccountType)
 	}
-	if decoded.BaseCurrency != commonv1.Currency_CURRENCY_UNSPECIFIED {
-		t.Errorf("Expected CURRENCY_UNSPECIFIED, got %v", decoded.BaseCurrency)
+	if decoded.BaseInstrumentCode != "" {
+		t.Errorf("Expected empty BaseInstrumentCode, got %v", decoded.BaseInstrumentCode)
 	}
 }
 
@@ -406,7 +406,7 @@ func TestFinancialBookingLogInitiatedEvent_ZeroVersion(t *testing.T) {
 		FinancialAccountType:    "DEBIT",
 		ProductServiceReference: "product-456",
 		BusinessUnitReference:   "bu-789",
-		BaseCurrency:            commonv1.Currency_CURRENCY_GBP,
+		BaseInstrumentCode:      "GBP",
 		CorrelationId:           "correlation-abc",
 		CausationId:             "causation-def",
 		Timestamp:               timestamppb.New(time.Now()),
@@ -435,7 +435,7 @@ func TestFinancialBookingLogInitiatedEvent_NegativeVersion(t *testing.T) {
 		FinancialAccountType:    "DEBIT",
 		ProductServiceReference: "product-456",
 		BusinessUnitReference:   "bu-789",
-		BaseCurrency:            commonv1.Currency_CURRENCY_GBP,
+		BaseInstrumentCode:      "GBP",
 		CorrelationId:           "correlation-abc",
 		CausationId:             "causation-def",
 		Timestamp:               timestamppb.New(time.Now()),

api/proto/meridian/events/v1/position_keeping_events.proto

@@ -5,7 +5,6 @@ package meridian.events.v1;
 import "buf/validate/validate.proto";
 import "google/protobuf/timestamp.proto";
 import "meridian/common/v1/error.proto";
-import "meridian/common/v1/types.proto";
 import "meridian/quantity/v1/quantity.proto";
 
 option go_package = "github.com/meridianhub/meridian/api/proto/meridian/events/v1;eventsv1";
@@ -29,10 +28,11 @@ message TransactionCapturedEvent {
   // amount_cents is the transaction amount in cents (or smallest currency unit)
   int64 amount_cents = 4 [(buf.validate.field).int64 = {gt: 0}];
 
-  // currency is the ISO 4217 currency code
-  meridian.common.v1.Currency currency = 5 [(buf.validate.field).enum = {
-    defined_only: true
-    not_in: [0]
+  // instrument_code is the ISO 4217 currency code or other instrument identifier (e.g., "GBP", "USD").
+  // Replaces the deprecated currency enum field.
+  string instrument_code = 5 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 50
   }];
 
   // direction indicates debit or credit
@@ -333,10 +333,11 @@ message OpeningBalanceRecordedEvent {
   // May be negative for overdrawn accounts
   int64 amount_cents = 3;
 
-  // currency is the ISO 4217 currency code
-  meridian.common.v1.Currency currency = 4 [(buf.validate.field).enum = {
-    defined_only: true
-    not_in: [0]
+  // instrument_code is the ISO 4217 currency code or other instrument identifier (e.g., "GBP", "USD").
+  // Replaces the deprecated currency enum field.
+  string instrument_code = 4 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 50
   }];
 
   // effective_date is when the opening balance becomes effective

api/proto/meridian/financial_accounting/v1/financial_accounting.proto

@@ -76,10 +76,11 @@ message FinancialBookingLog {
   // chart_of_accounts_rules defines the accounting rules to apply.
   string chart_of_accounts_rules = 5 [(buf.validate.field).string = {min_len: 1}];
 
-  // base_currency is the currency for this booking log.
-  meridian.common.v1.Currency base_currency = 6 [(buf.validate.field).enum = {
-    defined_only: true
-    not_in: [0]
+  // base_instrument_code is the instrument code for this booking log (e.g., "GBP", "USD", "kWh").
+  // Replaces the deprecated base_currency enum field. Supports the Universal Asset System.
+  string base_instrument_code = 6 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 50
   }];
 
   // status represents the current lifecycle state.
@@ -190,10 +191,11 @@ message InitiateFinancialBookingLogRequest {
   // chart_of_accounts_rules defines accounting rules.
   string chart_of_accounts_rules = 4 [(buf.validate.field).string = {min_len: 1}];
 
-  // base_currency is the currency for transactions.
-  meridian.common.v1.Currency base_currency = 5 [(buf.validate.field).enum = {
-    defined_only: true
-    not_in: [0]
+  // base_instrument_code is the instrument code for transactions (e.g., "GBP", "USD", "kWh").
+  // Replaces the deprecated base_currency enum field. Supports the Universal Asset System.
+  string base_instrument_code = 5 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 50
   }];
 
   // idempotency_key ensures exactly-once processing.

api/proto/meridian/financial_accounting/v1/financial_accounting_test.go

@@ -22,7 +22,7 @@ func TestFinancialBookingLogCreation(t *testing.T) {
 		ProductServiceReference: "prod-456",
 		BusinessUnitReference:   "bu-789",
 		ChartOfAccountsRules:    "rules-001",
-		BaseCurrency:            commonv1.Currency_CURRENCY_GBP,
+		BaseInstrumentCode:      "GBP",
 		Status:                  commonv1.TransactionStatus_TRANSACTION_STATUS_PENDING,
 		CreatedAt:               now,
 		UpdatedAt:               now,
@@ -35,8 +35,8 @@ func TestFinancialBookingLogCreation(t *testing.T) {
 	if log.FinancialAccountType != "DEBIT" {
 		t.Errorf("Expected DEBIT account type, got %v", log.FinancialAccountType)
 	}
-	if log.BaseCurrency != commonv1.Currency_CURRENCY_GBP {
-		t.Errorf("Expected GBP currency, got %v", log.BaseCurrency)
+	if log.BaseInstrumentCode != "GBP" {
+		t.Errorf("Expected GBP instrument code, got %v", log.BaseInstrumentCode)
 	}
 }
 
@@ -81,7 +81,7 @@ func TestInitiateFinancialBookingLogRequest(t *testing.T) {
 		ProductServiceReference: "prod-123",
 		BusinessUnitReference:   "bu-456",
 		ChartOfAccountsRules:    "rules-001",
-		BaseCurrency:            commonv1.Currency_CURRENCY_GBP,
+		BaseInstrumentCode:      "GBP",
 		IdempotencyKey: &commonv1.IdempotencyKey{
 			Key:        "idem-key-123",
 			TtlSeconds: 3600,
@@ -239,7 +239,7 @@ func TestResponseMessages(t *testing.T) {
 				ProductServiceReference: "prod-456",
 				BusinessUnitReference:   "bu-789",
 				ChartOfAccountsRules:    "rules-001",
-				BaseCurrency:            commonv1.Currency_CURRENCY_GBP,
+				BaseInstrumentCode:      "GBP",
 				Status:                  commonv1.TransactionStatus_TRANSACTION_STATUS_PENDING,
 				CreatedAt:               now,
 				UpdatedAt:               now,
@@ -258,7 +258,7 @@ func TestResponseMessages(t *testing.T) {
 				ProductServiceReference: "prod-456",
 				BusinessUnitReference:   "bu-789",
 				ChartOfAccountsRules:    "updated-rules",
-				BaseCurrency:            commonv1.Currency_CURRENCY_GBP,
+				BaseInstrumentCode:      "GBP",
 				Status:                  commonv1.TransactionStatus_TRANSACTION_STATUS_POSTED,
 				CreatedAt:               now,
 				UpdatedAt:               now,
@@ -278,7 +278,7 @@ func TestResponseMessages(t *testing.T) {
 					ProductServiceReference: "prod-1",
 					BusinessUnitReference:   "bu-1",
 					ChartOfAccountsRules:    "rules-1",
-					BaseCurrency:            commonv1.Currency_CURRENCY_GBP,
+					BaseInstrumentCode:      "GBP",
 					Status:                  commonv1.TransactionStatus_TRANSACTION_STATUS_PENDING,
 					CreatedAt:               now,
 					UpdatedAt:               now,

buf.yaml

@@ -42,4 +42,12 @@ breaking:
     # Package renamed from internal_bank_account to internal_account
     # All consumers updated in this PR
     - api/proto/meridian/internal_bank_account/v1/internal_bank_account.proto
+    # Intentional breaking changes: Remove Currency enum (asset-agnostic-accounts task 9)
+    # Fields changed from Currency enum to string instrument_code for Universal Asset System
+    # All consumers updated - see services/*/service/ and services/*/adapters/
+    - api/proto/meridian/events/v1/current_account_events.proto
+    - api/proto/meridian/events/v1/deposit_event.proto
+    - api/proto/meridian/events/v1/financial_accounting_events.proto
+    - api/proto/meridian/events/v1/position_keeping_events.proto
+    - api/proto/meridian/financial_accounting/v1/financial_accounting.proto
   ignore_unstable_packages: true