taler-android

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

taldir-protocol-version-mismatch.md (4168B)


      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 # The wallet and the Taler directory disagree on the protocol version
     18 
     19 Found while deploying a real directory beside the simulator's stack
     20 (`git://git.taler.net/taldir` at `3dca5c1b`, master of 2026-10-18): the wallet
     21 refuses to talk to it at all, before any alias is registered.
     22 
     23 **Severity: low-moderate, and it is an integration fact rather than a bug in
     24 either side.** Both are in development; the point is that today's heads do not
     25 interoperate, and the failure is reported as a generic error.
     26 
     27 ## What happens
     28 
     29 The directory's configuration endpoint answers:
     30 
     31 ```json
     32 {"version":"0:0:0","name":"taler-directory",
     33  "alias_types":[{"name":"email","challenge_fee":"EUR:0"}],"monthly_fee":"EUR:0"}
     34 ```
     35 
     36 and that version is a literal in the service:
     37 
     38 ```go
     39 // taldir, pkg/taldir/taldir.go:694
     40 cfg := VersionResponse{
     41     Version:    "0:0:0",
     42     Name:       "taler-directory",
     43 ```
     44 
     45 The wallet's client declares `1:0:0` and checks compatibility before using the
     46 service:
     47 
     48 ```ts
     49 // taler-util/src/http-client/taldir.ts:53
     50 public static readonly PROTOCOL_VERSION = "1:0:0";
     51 ```
     52 
     53 ```ts
     54 // taler-util/src/operation.ts:166, in carefullyParseConfig
     55 if (!LibtoolVersion.isCompatible(clientVersion, minBody.version)) {
     56     throw TalerError.fromUncheckedDetail({
     57         code: TalerErrorCode.GENERIC_CLIENT_UNSUPPORTED_PROTOCOL_VERSION,
     58         …
     59         detail: `Unsupported protocol version, client supports ${clientVersion}, server supports ${minBody.version}`,
     60     });
     61 }
     62 ```
     63 
     64 `1:0:0` against `0:0:0` is incompatible in libtool terms, so `lookupAlias`,
     65 `registerAlias` and `completeRegisterAlias` all fail at the first step. What
     66 reaches the caller is not the version detail but
     67 `WALLET_ALIAS_REGISTRATION_FAILED` with the hint "could not read the
     68 configuration of the directory service" — the specific reason is thrown away
     69 by `taldir.ts`'s own `default:` branch.
     70 
     71 For contrast, the mailbox service gets this right: `taler-mailbox`'s
     72 `Makefile.in` carries `LT_VERSION="1:1:0"` and passes it in at build time, and
     73 `1:0:0` against `1:1:0` is compatible.
     74 
     75 ## How it was established
     76 
     77 Deploy the directory and ask it:
     78 
     79 ```bash
     80 git clone git://git.taler.net/taldir && cd taldir
     81 GOFLAGS=-mod=vendor go build -o taldir-server ./cmd/taldir-server
     82 ./taldir-dbinit -c sim.conf && ./taldir-server -c sim.conf &
     83 curl -s http://127.0.0.1:11001/config
     84 ```
     85 
     86 Then point wallet-core at it (the app cannot be pointed anywhere, see
     87 [`alias-registration-hardcodes-the-directory.md`](alias-registration-hardcodes-the-directory.md)):
     88 
     89 ```bash
     90 taler-wallet-cli --wallet-db /tmp/w.sqlite3 advanced api lookupAlias \
     91   '{"alias":"sim@example.com","aliasType":"email","taldirBaseUrl":"http://127.0.0.1:11001/"}'
     92 ```
     93 
     94 With the service as it ships, that fails. With one character changed in
     95 `taldir.go` (`0:0:0` → `1:0:0`) the whole flow — register, challenge,
     96 complete, look up — works on the first attempt.
     97 
     98 ## Suggested fix
     99 
    100 Whichever side is wrong about the number, two things would have helped:
    101 
    102 * taldir should take its protocol version from `LT_VERSION` at build time, the
    103   way `taler-mailbox` does, rather than hard-coding it in the handler;
    104 * `taldir.ts` should pass the configuration error through instead of replacing
    105   it: its `default:` branch turns a precise
    106   `GENERIC_CLIENT_UNSUPPORTED_PROTOCOL_VERSION` ("client supports 1:0:0,
    107   server supports 0:0:0") into "could not read the configuration of the
    108   directory service", which is what an operator would have to debug from.