Multi-Currency Wallets Without Losing Auditability
Designing conversions as linked financial events instead of balance edits. Adding a currency to a wallet product is not simply adding another currency code to a transaction table. Each user can own multiple balances, every currency has different decimal rules, and conversions affect two wallets at once. Historical transactions must retain the rate used at execution, even after market or…
Designing multi-currency wallets requires handling conversions as distinct financial events rather than merely adjusting balances. A single wallet product must accommodate multiple currency balances, each with unique decimal rules. Conversions impact two wallets simultaneously.
Historical transactions must retain the exchange rate at the time of execution, even if market or configured rates alter later. Every user-currency pair should have a dedicated wallet. Enforce uniqueness with a database constraint: a user can have only one active wallet per supported currency.
Currency data should originate from a controlled configuration, including code, precision, funding capability, withdrawal capability, display symbol, and activation state. View conversions as financial transactions that generate immutable records. Each record should include a reference, source currency and amount, destination currency and amount, applied exchange rate, rate source, relevant context, and execution time.
Perform conversions within a single database transaction. Lock the source and destination wallets in a consistent order to minimize deadlock risks when concurrent conversions involve the same currency pair in opposite directions. Capture the applied rate in the transaction snapshot. Do not recalculate the conversion using the current exchange rate, as this would undermine the historical record.
If staff can adjust exchange rates, maintain an audit trail that records the previous rate, new rate, the actor who made the change, timestamp, and rationale. Existing conversions should remain untouched. Use decimal arithmetic for wallet balances, as floating-point arithmetic is unsuitable for financial calculations. Define rounding rules at the business boundary, such as wallet storage precision, quote display precision, provider submission precision, and ledger settlement precision. Round once at the appropriate boundary and persist the final value.
Legacy interfaces should remain separate to accommodate older clients expecting a single primary balance. A compatibility property can designate a primary wallet without reverting the legacy column to its previous role. Implement the migration code explicitly, ensuring reversibility where possible, and follow up with constraints that prevent the old and new systems from diverging over time.
The key principle: a multi-currency wallet is a set of currency-specific ledgers linked by immutable conversion records. The exchange rate, rounding decision, and the two wallet outcomes constitute one coherent financial event. Safeguarding these elements ensures that historical balances remain coherent as currency values and pricing rules evolve.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
