Document unit model and flag BCH exchange rate exception for investigation
CI / build-and-test (push) Failing after 3h13m14s
CI / docker (push) Has been cancelled

accounting-core spec: clarified Money representation unit model:
  fiat cents ↔ crypto satoshis, dollars ↔ microcoins, both 2 decimal
  places. 1 microcoin = 100 satoshis, same as 1 dollar = 100 cents.

exchange-rates spec: added investigation warning for BCH exception.
  If BTC and BCH both use satoshi/microcoin units, the ÷1,000,000
  micro-BTC scaling should apply to BCH too. The current exception
  (BCH stored at face value) may be incorrect and could produce
  conversions off by 6 orders of magnitude. Action required: verify
  end-to-end with known amounts before live BCH conversions.

Made-with: Cursor
This commit is contained in:
2026-04-10 16:51:43 +02:00
parent 3be41639ea
commit b842934f39
2 changed files with 28 additions and 4 deletions
@@ -174,15 +174,26 @@ Each financial account SHALL have an optional owner (user) who serves as the bud
- **THEN** that user receives attestation tasks for expenses and invoices charged to that account
### Requirement: Money representation
The system SHALL represent all monetary amounts as Int64 values in the smallest unit of the currency (cents for fiat, satoshis for BTC/BCH). Display formatting SHALL convert to the appropriate decimal representation based on the currency's unit scale (100 for most fiat, 1,000,000 for microbitcoin display).
The system SHALL represent all monetary amounts as Int64 values in the smallest unit of the currency. The unit model is uniform across fiat and crypto:
- **Fiat:** cents (1/100 of the currency unit). Display unit = dollar/euro/krona with 2 decimal places.
- **Crypto:** satoshis (1/100,000,000 of BTC/BCH). Display unit = microcoin (1/1,000,000 of BTC/BCH) with 2 decimal places.
- **The equivalence:** dollars ↔ microcoins, cents ↔ satoshis. Both use 2 decimal places for display.
- **1 microcoin = 100 satoshis**, just as 1 dollar = 100 cents.
This means `formatCents()` works identically for fiat and crypto: divide by 100, show 2 decimal places. The "100" divisor represents cents-per-dollar for fiat and satoshis-per-microcoin for crypto.
#### Scenario: Fiat amount storage
- **WHEN** an amount of €42.50 is stored
- **THEN** the internal representation is 4250 (cents) with currency EUR
#### Scenario: Crypto amount storage
- **WHEN** an amount of 0.005 BCH is stored
- **THEN** the internal representation is 500000 (satoshis) with currency BCH
- **WHEN** an amount of 3.25 µBTC is stored
- **THEN** the internal representation is 325 (satoshis, i.e., "cents" of a microcoin) with currency BTC
#### Scenario: Whole-coin crypto conversion
- **WHEN** 0.5 BCH needs to be stored
- **THEN** 0.5 BCH = 500,000 µBCH = 50,000,000 satoshis, stored as 50000000
#### Scenario: Cross-currency display
- **WHEN** a report displays amounts in multiple currencies
@@ -45,7 +45,7 @@ The BitPay rate provider SHALL parse the API response as JSON using a proper JSO
- **THEN** the snapshot attempt fails, the error is logged, and the fallback provider is tried
### Requirement: Micro-BTC storage scaling
The system SHALL store exchange rates divided by 1,000,000 (micro-BTC scaling) for all currencies EXCEPT BCH, which is stored at face value. This matches the v5 convention where amounts are expressed in the smallest unit (satoshis = 1/100,000,000 BTC, but displayed as microbitcoin = 1/1,000,000 BTC). `GetConversionRate` SHALL account for this scaling. Getting this wrong would silently produce rates off by 6 orders of magnitude.
The system SHALL store exchange rates divided by 1,000,000 (micro-BTC scaling) for all currencies EXCEPT BCH, which is stored at face value. This matches the v5 convention. `GetConversionRate` SHALL account for this scaling. Getting this wrong would silently produce rates off by 6 orders of magnitude.
#### Scenario: Fiat rate storage
- **WHEN** BitPay reports 1 BTC = 50,000 USD
@@ -59,6 +59,19 @@ The system SHALL store exchange rates divided by 1,000,000 (micro-BTC scaling) f
- **WHEN** a conversion from EUR to USD is computed using stored micro-BTC-scaled rates
- **THEN** the scaling cancels out in the division and the result is correct
### ⚠ Investigation needed: BCH exception correctness
**Unit model (confirmed):** All monetary amounts in the system use the same Int64 "cents" model:
- Fiat: cents (1/100 of dollar/euro/krona) — display unit is the dollar/euro with 2 decimal places
- Crypto: satoshis (1/100,000,000 of BTC/BCH) — display unit is the microcoin (1/1,000,000 of BTC/BCH) with 2 decimal places
- The equivalence is: dollars↔microcoins, cents↔satoshis. Both display with 2 decimal places.
**The question:** If BTC and BCH both use the same satoshi/microcoin unit scale, then the micro-BTC scaling (÷1,000,000) converts "rate per whole BTC" to "rate per microcoin" — aligning the rate with the display unit. This logic should apply equally to BCH. The BCH exception (storing at face value without the ÷1,000,000) may be incorrect for exchange rate purposes, since BCH amounts are also stored in satoshis and displayed as microcoins.
**Risk:** If the BCH exception is wrong, BCH↔fiat conversions would be off by 6 orders of magnitude. However, this was preserved from v5 where it may have been correct for reasons not yet fully understood, or BCH conversions may not have been actively used in production.
**Action required before live BCH conversions:** Verify end-to-end with a known amount — convert a BCH value to SEK using the stored rates and compare against a public rate source. This will definitively confirm whether the BCH exception is correct or a bug that needs fixing.
### Requirement: Currency conversion uses double arithmetic
The system SHALL use `double` (not `decimal`) for intermediate exchange rate calculations, matching v5 behavior. This is a deliberate choice: `decimal` causes hard-to-debug precision issues in practice, and exchange rates are inherently fluctuating snapshots where sub-cent precision is not meaningful.