taler-android

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

README.md (4518B)


      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 # Services beside the stack
     18 
     19 `taler-unified-setup.sh` brings up the exchange, the merchant, the bank, donau
     20 and the auditor. Two more services the wallet can use are not part of it, and
     21 the wallet has screens for both:
     22 
     23 | service | repository | port | what it unlocks in the app |
     24 | --- | --- | --- | --- |
     25 | Taler mailbox | `git://git.taler.net/taler-mailbox` | 11000 | the Mailbox screen: register, list, refresh, delete |
     26 | Taler directory | `git://git.taler.net/taldir` | 11001 | nothing, see below — but it makes the contacts operations testable through wallet-core |
     27 
     28 Both are Go services with vendored dependencies, so they build without network
     29 access to a module proxy — but they need **Go 1.25**, which Debian does not
     30 have yet; `GOTOOLCHAIN=auto` (the default) downloads it:
     31 
     32 ```bash
     33 git clone git://git.taler.net/taler-mailbox && cd taler-mailbox
     34 GOFLAGS=-mod=vendor go build -ldflags "-X main.ltversion=1:1:0" -o /tmp/ ./cmd/...
     35 ```
     36 
     37 The `ltversion` ldflag matters: without it the service advertises an empty
     38 protocol version and the wallet refuses it (`carefullyParseConfig`).
     39 
     40 ## Deploying them
     41 
     42 The simulator runs them on the emulator host, beside the stack:
     43 
     44 ```
     45 /opt/taler-mailbox/{mailbox-server,mailbox-dbinit,sim.conf}
     46 /opt/taldir/{taldir-server,taldir-dbinit,sim.conf,sim-validator.sh}
     47 ```
     48 
     49 `services/mailbox-sim.conf` and `services/taldir-sim.conf` here are the
     50 deployed configurations. Databases are Postgres, created once:
     51 
     52 ```bash
     53 createdb -h /var/run/postgresql talermailbox
     54 createdb -h /var/run/postgresql talerdir
     55 cd /opt/taler-mailbox && ./mailbox-dbinit -c sim.conf
     56 cd /opt/taldir      && ./taldir-dbinit  -c sim.conf
     57 cd /opt/taler-mailbox && ./mailbox-server -c sim.conf -L DEBUG > /tmp/mb.log 2>&1 &
     58 cd /opt/taldir        && ./taldir-server  -c sim.conf -L DEBUG > server.log 2>&1 &
     59 ```
     60 
     61 They keep their own databases, so unlike `exchange2` they survive a stack
     62 restart and need starting only once. Their ports are in `stack.sh`'s port list,
     63 so `emu.sh reverse` maps them into every emulator.
     64 
     65 ## Things that cost an hour each
     66 
     67 * **`localhost` is not `127.0.0.1`.** Both services bind `127.0.0.1` only, and
     68   wallet-core resolves `localhost` to `::1` first, so a `localhost` URL gets
     69   ECONNREFUSED. Use the numeric address in anything handed to wallet-core.
     70 * **Every `GetDuration`/`GetAmount` in the mailbox server errors out when its
     71   key is missing**, default or no default, so `sim.conf` spells out every fee
     72   and every duration.
     73 * **`taldir-dbinit` reads `[taldir-pq]` while `taldir-server` reads
     74   `[directory-pq]`.** The config carries both, saying the same thing.
     75 * **The directory's protocol version is a literal `0:0:0`** in
     76   `pkg/taldir/taldir.go`, which the wallet refuses; the deployment patches it
     77   to `1:0:0`. See `findings/taldir-protocol-version-mismatch.md`.
     78 * **The email validator is a command.** `[directory-validator-email] COMMAND`
     79   is run as `COMMAND <alias> <challenge> <topic> <message>`, so
     80   `sim-validator.sh` appends the alias and the challenge to
     81   `/opt/taldir/challenges.log` — the simulator's stand-in for reading a
     82   validation email, and the only way a scenario can complete a registration.
     83 
     84 ## Why the directory unlocks nothing in the app
     85 
     86 The app hard-codes `https://taldir.gnunet.org` in two files, so no deployment
     87 can be reached from it; the service is still worth having, because wallet-core
     88 takes the base URL as a parameter and the three contact operations can be
     89 driven through `taler-wallet-cli advanced api`. See
     90 `findings/alias-registration-hardcodes-the-directory.md`.
     91 
     92 ## Sync
     93 
     94 `git://git.taler.net/sync` is *not* deployed: the Android wallet has no backup
     95 or sync feature at all — no screens, and none of the wallet-core backup
     96 operations appear in `coverage/app-operations.txt`. Deploying it would add
     97 nothing to drive.