taler-android

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

amounts-without-currency-specification.md (5426B)


      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 # Amounts reach two screens without their currency specification
     18 
     19 Found by the `withdraw_account_tabs` and `peer_push_receive` scenarios: the
     20 wire transfer instructions and the incoming peer-payment prompt print amounts
     21 in the wallet's fallback notation ("5.00 EUR") while the rest of the app shows
     22 "€5.00". On the transfer screen the two notations appear in the same sentence.
     23 
     24 **Severity: low.** Cosmetic, but both are screens the user acts on: one carries
     25 the amount to copy into a banking app, the other is where a payment is
     26 accepted.
     27 
     28 ## What happens
     29 
     30 The manual-withdrawal instructions say:
     31 
     32 ```
     33 You need to transfer 5.00 EUR from your regular bank account to the payment
     34 service to receive €4.88 as digital cash in this wallet.
     35 ```
     36 
     37 Both amounts are EUR. The first is rendered "5.00 EUR", the second "€4.88".
     38 
     39 The sentence is `R.string.withdraw_manual_ready_intro` and takes two
     40 arguments:
     41 
     42 ```kotlin
     43 // wallet/src/main/java/net/taler/wallet/transfer/TransferIBAN.kt:55
     44 stringResource(
     45     R.string.withdraw_manual_ready_intro,
     46     transfer.transferAmount,          // no currency specification
     47     transactionAmountEffective,       // .withSpec(spec) by the caller
     48 )
     49 ```
     50 
     51 `ScreenTransfer` applies the currency specification to the effective amount
     52 before passing it down (`transfer.amountEffective.withSpec(spec)`), but
     53 `transfer.transferAmount` is handed over as it came from wallet-core. With
     54 `spec == null`, `Amount.toString()` takes its no-specification branch and
     55 prints "5.00 EUR"; with a specification it prints "€5.00".
     56 
     57 The same pairing appears in every transfer screen:
     58 
     59 - `transfer/TransferTaler.kt:52,61`
     60 - `transfer/TransferIBAN.kt:56,65,152,157`
     61 - `transfer/TransferCyclos.kt:47,97`
     62 
     63 and in the deposit KYC variant of the sentence
     64 (`send_deposit_kyc_auth_intro_bank`).
     65 
     66 ## The same thing on the incoming peer-payment prompt
     67 
     68 Accepting money from another wallet shows:
     69 
     70 ```
     71 Do you want to receive this payment?
     72 from the simulator's peer
     73 Total:        1.00 EUR
     74              −0.09 EUR
     75 Receive payment
     76 ```
     77 
     78 `IncomingComposable` takes no `CurrencySpecification` parameter at all, so both
     79 the total and the fee are rendered with `Amount.toString()` on an amount that
     80 never had one:
     81 
     82 ```kotlin
     83 // wallet/src/main/java/net/taler/wallet/peer/IncomingComposable.kt:145
     84 text = terms.contractTerms.amount.toString(),
     85 // ...:159
     86 stringResource(R.string.amount_negative, fee)
     87 ```
     88 
     89 The same composable serves `IncomingPushPaymentScreen` and
     90 `IncomingPullPaymentScreen`, so this is the prompt for both receiving a push
     91 payment and paying an invoice. Its sibling screens get this right —
     92 `TransactionAmountInfo` and `PeerQrCode` are both passed `withSpec(spec)`.
     93 
     94 ## Reproduce by hand — the transfer instructions
     95 
     96 Needs an exchange that offers a manual (not bank-integrated) withdrawal; any
     97 deployment does, including a plain `taler-unified-setup.sh` stack.
     98 
     99 1. Install a debug build, enable **Developer mode**, add the exchange.
    100 2. On the main screen tap **Withdraw**, enter an amount, tap
    101    **Confirm withdrawal** — do not use the bank's own "withdraw" button, as
    102    that is the bank-integrated flow.
    103 3. On the pending transaction tap **Wire transfer instructions**.
    104 4. The first sentence reads "You need to transfer 5.00 EUR … to receive €4.88
    105    …".
    106 
    107 ## Reproduce by hand — the peer prompt
    108 
    109 Needs a second wallet (`taler-wallet-cli` will do) with a balance:
    110 
    111 1. `taler-wallet-cli peer-send --exchange <url> --summary test EUR:1`
    112 2. Hand the `taler://pay-push/…` URI it prints to the wallet under test.
    113 3. The prompt reads "Total: 1.00 EUR" and "−0.09 EUR".
    114 
    115 ## Reproduce with the simulator
    116 
    117 ```bash
    118 ssh root@tripwire.taler.net
    119 cd /opt/taler-sim/driver
    120 python3 ../findings/repro_unspecced_amounts.py             # both screens
    121 SIM_WORKER=4 python3 suite.py withdraw_account_tabs peer_push_receive
    122 ```
    123 
    124 The reproducer prints the offending lines from each screen; the scenarios'
    125 `suite-w4-*-summary.json` quotes them in its notes.
    126 
    127 ## Suggested fix
    128 
    129 Give `IncomingComposable` a `spec: CurrencySpecification?` parameter — both its
    130 screens have the exchange base URL in hand and so can use
    131 `rememberCurrencySpec` as the transaction screens do — and apply it to the
    132 total and the fee.
    133 
    134 On the transfer screens, pass `transfer.transferAmount.withSpec(spec)` the way
    135 the effective amount already is — the specification is in scope in `ScreenTransfer`, which is where
    136 `transactionAmountEffective` is computed, so the simplest fix is to compute
    137 both there and hand both down formatted. Note the spec belongs to the
    138 *transfer* currency, which for a currency-converting account is not the
    139 wallet's currency, so the right specification is the account's
    140 `currencySpecification` where it has one.