Feat/534 multi currency display

[CHKM001]

PR #534 Multi-Currency Portfolio Display & Accounting

Summary

Adds user-preferred display currency with additive displayAmount/displayCurrency fields on portfolio and goals responses. Strictly presentation layer — all internal accounting stays USD/token-native.

What's Included

Data Model

• User.displayCurrency field (default: "USD") + migration with rollback

FX Utility (src/utils/fxConvert.ts)

• Static rate table for 15 major currencies
• convertUsdToCurrency() — returns null when rate unavailable (graceful degradation)
• withDisplayCurrency() — attaches display fields without replacing canonical USD amount
• Display rounding to 2 decimal places; canonical figures keep full precision

Settings Endpoint (src/routes/settings.ts)

• PUT /api/v1/settings — update displayCurrency
• Validates against supported currency list

Updated Responses

• GET /api/v1/portfolio/:userId — adds displayTotalBalance, displayTotalEarnings, displayCurrency
• GET /api/v1/goals/:id/progress — adds displayTargetAmount, displayCurrentAmount, displayCurrency

API Changes

PUT /api/v1/settings

// Request
{ "displayCurrency": "EUR" }

// Response
{ "userId": "...", "displayCurrency": "EUR" }

GET /api/v1/portfolio/:userId (response additions)

{
  "totalBalance": 10000,
  "displayTotalBalance": 9200,
  "displayTotalEarnings": 500,
  "displayCurrency": "EUR"
}

Key Design Decisions

1. Additive only: amountUsd is never removed or replaced — it stays the source of truth
2. Graceful degradation: When FX unavailable, displayAmount is omitted; amountUsd always present
3. No stale caching: Every response converts fresh at request time
4. Display vs tax currency: Display currency is presentation-only; tax reports use jurisdiction-native currency per Per-Jurisdiction Tax Profiles & Configurable Rule Sets #356
5. Historical figures: Converted at current rate, clearly documented as such

Supported Currencies

USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, INR, BRL, MXN, SGD, HKD, KRW

Test Results

• tests/unit/utils/fxConvert.test.ts — 10 tests covering conversion, rounding, graceful degradation, and field attachment

Documentation

• docs/MULTI_CURRENCY.md — full documentation including display vs tax currency distinction

Closes #534

[drips-wave]

@CHKM001 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits