taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

word-currency-symbol-glued-to-amount.md (4261B)


      1 <!--
      2   This file is part of GNU Taler
      3   (C) 2026 Taler Systems S.A.
      4 
      5   GNU Taler is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU General Public License as published by the Free Software
      7   Foundation; either version 3, or (at your option) any later version.
      8 
      9   GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     12 
     13   You should have received a copy of the GNU General Public License along with
     14   GNU Taler; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 -->
     16 
     17 # A word-shaped currency symbol is glued to the amount: "UNKNOWN0.00"
     18 
     19 Found while testing QR scanning: a code pointing at an order that does not
     20 exist leaves a failed purchase in the history whose amounts read
     21 **`UNKNOWN0.00`**.
     22 
     23 **Severity: low (cosmetic), and it is not limited to the UNKNOWN placeholder.**
     24 The same run showed a real payment prompt reading **`Total: EUR1.00`**, because
     25 the contract's currency specification gives `alt_unit_names[0] = "EUR"` rather
     26 than a sign. Any currency whose first alternative unit name is a word — a
     27 regional currency called `KUDOS`, or `EUR` as served by a backend that
     28 publishes no symbol — renders this way.
     29 
     30 ## What happens
     31 
     32 A purchase whose contract could not be downloaded:
     33 
     34 ```
     35 This transaction has failed or been abandoned
     36 Total      UNKNOWN0.00
     37 Paid       UNKNOWN0.00
     38 ```
     39 
     40 And an ordinary payment prompt, against a merchant whose currency
     41 specification carries no symbol:
     42 
     43 ```
     44 Simulator Shop
     45 Review order
     46 QR scanned order
     47 Total: EUR1.00
     48 ```
     49 
     50 wallet-core reports the amounts of a purchase whose contract it could not
     51 download with its placeholder currency:
     52 
     53 ```json
     54 "amountRaw":"UNKNOWN:0", "amountEffective":"UNKNOWN:0",
     55 "currencySpecification":{"name":"UNKNOWN", … ,"alt_unit_names":{"0":"UNKNOWN"}}
     56 ```
     57 
     58 ## Reproduce by hand
     59 
     60 1. Install a debug build and enable **Developer mode** in Settings.
     61 2. Share a `taler+http://pay/…` URI for an order id that does not exist into
     62    the wallet — scan it as a QR code, or share it as text. Against the
     63    simulator's stack:
     64    `taler+http://pay/localhost:8080/instances/sim/NOSUCHORDER12345/`
     65    (Any deployment works; the point is that the merchant has no such order.)
     66 3. The wallet opens a transaction that failed, with "Total" and "Paid" shown
     67    as `UNKNOWN0.00`.
     68 
     69 Expected: a separator, as in `0.00 UNKNOWN`, which is what the same formatter
     70 produces when there is no currency specification at all.
     71 
     72 ## Reproduce with the simulator
     73 
     74 ```bash
     75 ssh root@tripwire.taler.net
     76 cd /opt/taler-sim/driver
     77 python3 ../findings/repro_unknown_currency_formatting.py
     78 ```
     79 
     80 ## Why
     81 
     82 `CurrencySpecification.symbol` is defined as the first alternative unit name
     83 (`taler-kotlin-android/.../CurrencySpecification.kt:37`):
     84 
     85 ```kotlin
     86 val symbol: String? get() = altUnitNames[0]
     87 ```
     88 
     89 `Amount.toString()` then hands that to a currency formatter
     90 (`Amount.kt:272`):
     91 
     92 ```kotlin
     93 val format = NumberFormat.getCurrencyInstance()
     94 s.currencySymbol = spec.symbol ?: ""
     95 …
     96 return if (spec.symbol != null) fmt else "$fmt $currency"
     97 ```
     98 
     99 `NumberFormat.getCurrencyInstance()` places the symbol immediately before the
    100 number in most locales, which is right for `€` or `$` and wrong for a word.
    101 The branch that already formats as `"$fmt $currency"` is only taken when there
    102 is no symbol at all.
    103 
    104 The existing unit test covers a one-character symbol (`"ク"`), so the word case
    105 is untested.
    106 
    107 ## Suggested fix
    108 
    109 Use the currency-instance layout only for a sign-shaped symbol, and fall back
    110 to the spaced form otherwise, e.g. in `Amount.toString()`:
    111 
    112 ```kotlin
    113 val sign = spec.symbol?.takeIf { it.length <= 2 && !it.any(Char::isLetter) }
    114 …
    115 return if (sign != null) fmt else "$fmt ${spec.symbol ?: currency}".trim()
    116 ```
    117 
    118 An `AmountTest` case with `symbol = "KUDOS"` would pin it.
    119 
    120 ## Also worth deciding
    121 
    122 The wallet records a *failed purchase transaction* for a URI that pointed at
    123 nothing, so a mistyped or stale QR code leaves a permanent entry in the
    124 history. Reporting the failure without keeping a transaction may be the better
    125 behaviour; that is a product decision rather than a defect.