Currency Management#

Overview#

Sure uses a static YAML catalog as the single source of truth for all currency definitions. This catalog drives Money::Currency object construction, formatting, validation, and UI selection throughout the app. There is no runtime lookup against an external currency service — if a currency code is not in the catalog, it is unknown to the system.

The Currency Catalog (config/currencies.yml)#

config/currencies.yml defines every supported currency as a keyed YAML entry (lowercase ISO code → attributes). Each entry carries:

The catalog includes fiat currencies (USD at priority 1, EUR at priority 2, etc.), precious metals (XAU, XAG, XPD, XPT), and a small set of crypto assets (BTC, DOGE, USDC) 1 2.

Money::Currency — The Catalog Interface#

lib/money/currency.rb wraps the YAML catalog:

• Money::Currency.new(code) — looks up code (downcased) in @@instances cache, or loads from YAML. Raises Money::Currency::UnknownCurrencyError if the code is absent 3.
• Money::Currency.all — parses and memoizes the full YAML file via YAML.safe_load 4.
• Money::Currency.as_options — returns all instances sorted by priority then name; used for UI dropdowns 5.
• Money::Currency.popular — returns the first 12 by priority; used for quick-select UI 6.

Instance attributes (symbol, minor_unit_conversion, default_precision, etc.) are read directly from the YAML data 7.

Currency Validation: Two Layers#

1. Account model (persistence layer)#

Account validates presence of currency but does not validate that the code exists in the catalog 8. Any 3-letter or non-standard string can be saved as an account's currency if it passes the presence check. The Family model enforces catalog membership more strictly: normalize_currency_code calls Money::Currency.new(value) and rescues UnknownCurrencyError, silently dropping invalid codes 9.

Family#enabled_currency_codes controls the set of currencies available to a family. If enabled_currencies is nil, all catalog entries are available; otherwise only the explicit list plus the primary currency is returned 10. The primary currency falls back to "USD" if not set 11.

2. Provider-import normalization layer (CurrencyNormalizable)#

app/models/concerns/currency_normalizable.rb is included by provider sync models (Plaid, SimpleFIN, LunchFlow, Enable Banking) to sanitize incoming currency codes before storage:

1. Rejects blank values → nil 12
2. Normalizes to uppercase 13
3. Enforces a 3-letter [A-Z]{3} format — rejects codes like DOGE or USDC 14
4. Validates against the catalog via Money::Currency.new — rejects codes like XXX 15

Invalid codes are logged as warnings and return nil, letting callers apply their own fallback 16.

Gap: CurrencyNormalizable only enforces 3-letter codes. Crypto tickers like BTC/DOGE that appear as holding currency fields bypass this concern; the Holding model validates only presence, not catalog membership 17.

Crypto Accounts: Fiat Valuation vs. Crypto Holdings#

Crypto accounts (type "Crypto") have a deliberate split between account-level valuation and individual asset tracking:

• Account currency = fiat. When creating a Coinbase account, native_balance.currency from the API payload (e.g., USD, EUR, GBP) becomes the account's currency 18. The account balance reflects the fiat value of all holdings combined; cash_balance is set to 0 because no cash is held directly 19.
• Holdings carry the crypto asset. Each holding belongs to a Security resolved with a CRYPTO: ticker prefix (e.g., CRYPTO:BTC). The holding's currency field stores the fiat denomination of the amount (i.e., the valuation currency, not the asset's own ticker) 20.

For Coinbase, CoinbaseAccount::HoldingsProcessor derives the fiat price via native_balance.amount / quantity, then stores amount in native_currency 21 22. For CoinStats, CoinstatsAccount::HoldingsProcessor similarly resolves holdings with CRYPTO: prefixed tickers and passes inferred_currency (a fiat code) as the holding currency 23.

When computing weight or amount_in_account_currency, Holding calls Money#exchange_to to convert the holding amount into the account's fiat currency; if the exchange rate is missing, it rescues ConversionError and falls back to the raw amount 24.

Key Files#