Actual Budget Multi-Currency Discussion

Notes and Discussion points for adding Multi-Currency to Actual Budget

Discord - #Ideas - Support for Multi Currency Budget

How to use multi-currency in Actual Budget until it is officially released

User Interface

Note

The images below are ideas and not the final layout/design.

Creating a New Budget

Currently, when creating a new budget, no questions are asked. A new budget file is created and it is up to the user to find and change settings or rename the budget file. Since it would be better to set the currency before the budget file is created I would suggest a "New Budget" popup be created similar to the "Add Account" popup. This "New Budget" popup would have the ability to set the budget name, base currency, and a few setting such as formatting.

Creating New Account

Add "Currency" dropdown to Create Account dialog. The currency should default to the base budget currency. Once created, the account currency will not be able to be changed.

Settings Page

Add Currency selection to the Formatting section of the settings page.

If transitioning a previous budget, currency will be shown "default", "unknown", "not set", or something similar.

Once a currency is selected, the currency type should display, but should NOT be able to be changed.

Note

In the future, it may be possible to change the budget currency from the settings page and have each account keep it's own account currency. This would allow for keeping the same budget file while being able to budget in different currencies at different times.

Account Page (base budget accounts)

Base budget currency code should be displayed in the account header. The only other change would be to individual transactions.

Transactions

Add column for either "Exchange Rate" or "FX".
If there is an exchange rate then the rate would be listed along with the two amounts. The two amounts should show the currencies. And the FX amount would need a currency selection box unless it is a transfer.
If there is no exchange rate then an icon can be displayed to be able to convert the transaction to a FX transaction. This would be usefull for the one-off transactions (buying food in Australia with a US credit/debit card). Both of the currencies could be listed: FX currency from POS and account currency from the credit/debit card statement.

For useage, see Account Page (non base budget account) - Transactions

Account Page (non base budget accounts)

The account currency should be displayed in the account header. The account value should be in the account currency with an option to display the base currency.

Transactions

Adding a transaction will default to the exchange rate set to the last know exchange rate for that account. The user can adjust the exchange rate. If the user does change the exchange rate a popup should be displayed asking if this exchange rate should be added to the exchange rate table.

The user would then enter the transaction amount in the account currency and the base currency would auto calculate from the exchange rate. If the base currency amount is changed then the exchange rate would be calculated from the account currency and the base currency.
Account currency should never be auto calculated.

Sidebar

Add new button titled 'FX Rates' in the More section with Payees and Rules.
Account Groups (For budget and Off Budget) will keep the same base currency total (which will be calculated from the current FX rate applied to the current FX account balance). However, an account in a different currency will need to display either:

1. List the currency code next to the name with the base currency code next to the amount. The base currency amount will be calculated from the current FX balance then converted to base budget currency with the latest exchange rate found in the FX Rate table.
   Regular Cash (EUR) USD 102.34
2. List the currency code next to the current FX balance.
   Regular Cash EUR 92.40

Note

A settings option could be used to display the currency symbol too.
Regular Cash (EUR) 92.40 €
as shown in actualbudget/actual#1132 (comment)

FX Rate Page (new page)

The FX Rate Page should list the FX rates by date and be able to sort/filter by date, currency, account, or rate. This will be a new page and be in the same group as Payees and Rules.

Date	Currency	Account	Rate	Multiplier
10/01/2024	EUR	Regular Cash	1.1076	1
09/30/2024	AUD	Travel Cash	0.693083	1
09/15/2025	EUR	Regular Cash	1.1012	1
09/10/2024	AUD	Travel Cash	0.674169	1

Note

The multiplier field may not be necessary, but rmillian/multi-currency uses the multiplier field and some currencies have a high exchange rate. (1 Euro = 4,030.86 Ugandan Shilling)

Next Steps

Step 1 - Duplicate and Snapshot Budget File

• Pull Request: actualbudget/actual#3847
• Preview: https://deploy-preview-3847.demo.actualbudget.org
  
  

Step 2 - Add Currency Support

• Pull Request: Private Repository
• Preview:
  
  

Actual Budget currently does not use any specific currency. Currently, all transaction amounts are stored in the SQLite database as an Integer using a minor unit of 2. This means that before the amount is stored it is multiplied by 100 ($123.45 is stored as 12345). This works for 255 of the 264 currencies listed in ISO 4217, but does not work for all currencies.

Currency Minor Units (from ISO 4217)

0 minor units - 31 currencies
2 minor units - 224 currencies
3 minor units - 7 currencies (Bahraini Dinar, Iraqi Dinar, Jordanian Dinar, Kuwaiti Dinar, Libyan Dinar, Rial Omani, Tunisian Dinar)
4 minor units - 2 currencies (Unidad de Fomento, Unidad Previsional)

ISO 4217 can be downloaded as an XML file from :
https://www.iso.org/iso-4217-currency-codes.html
list-one.xml was downloaded from iso.org.
The XML file is organized by country name. AB will need to turn this XML file organized by country name to a JS Objects organized by currency code (UNITED STATES OF AMERICA (THE) -> USD or AUSTRIA -> EUR).
Example Currency Objects
ISO 4217 does not include currency symbols. Current list of symbols can be found at:

• https://www.xe.com/symbols/
• https://en.wikipedia.org/wiki/Currency_symbol#List_of_currency_symbols_currently_in_use

currency_symbols.csv was extracted from xe.com/symbols

Structure for Currency Object:

{
  code: string                // "AFN"
  name: string,               // "Afghani"
  number: number,             // 971
  minorUnits: number,         // 2
  symbol: string,             // "؋"
  country: Array<string>,     // [ "AFGHANISTAN" ]
}

Example: (currencies/iso4217/INR.ts)

export const INR: Currency = {
  code: 'INR',
  name: 'Indian Rupee',
  number: 356,
  minorUnits: 2,
  countries: ['BHUTAN', 'INDIA'],
};

Step 2 - Todo

1. • Create Currency type and list of currencies
2. • Create lookup functions such as:

     getCurrency(currencyCode): Currency
     getCurrencyList(list?: 'iso4217' | 'crypto'): Array<Currency>
     

3. • Create MonetaryUnit class to hold currency value
4. • Implement MonetaryUnit: Convert AB's current fixed minor units to minor unit based on selected currency (which could also be no currency).

Discord Discussion

Step 3 - Implement Currency Support

Step 3 - Todo

1. • Add {currency: string} field to AB global settings as the base budget currency. Add currency selection to Settings page for a one-time setting of currency.

Warning

Changing a base currency would require a conversion to the new currency and is beyond the current scope of the project. This may be a future feature, but not initial. Once the base currency is set, the settings should be grayed out and only display the base currency.

2. • Possibly add option to view currency symbols.
3. • Add currency to account and transaction tables

Step 4 - FX rate Table

For now, the FX rate table will be manual entry only. In the future automatic lookup can be figured out, but stay simple for the beginning. Transfer transactions can trigger an automatic entry into the FX rate table, but regular purchase will not.

Step 3 - Todo

1. Create new table in SQLite that would include the following fields:

   date:              // same date format currently use in other tables
   code: text         // EUR, USD, AUD, etc
   account:           // same account format currently use in other tables
   rate: integer      // stored as an integer with 6 significant figures
   

2. Create FX rate CRUD functions