summaryrefslogtreecommitdiff
path: root/taler-wallet.rst
blob: 18ae0496a330f5bdd60ecb113e2211f018a2d5b2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
GNU Taler Wallet Manual
#######################

The GNU Taler wallet allows customers to withdraw and spend digital cash.

.. _command-line-wallet:

Command-line Wallet
===================

The command-line wallet is used primarily for testing by developers.

Building from source
--------------------

.. code-block:: console

  $ git clone https://git.taler.net/wallet-core.git
  $ cd wallet-core
  $ ./bootstrap
  $ ./configure --prefix=$INSTALL_PREFIX
  $ make && make install

The wallet command-line interface should then be available as ``taler-wallet-cli`` under ``$INSTALL_PREFIX/bin``.

Installation via NPM
--------------------

The wallet can also obtained via NPM, the Node Package Manager.

To install the wallet as a global package, run:

.. code-block:: console

  $ npm install -g taler-wallet
  # check if installation was successful
  $ taler-wallet-cli --version

To install the wallet only for your user, run:

.. code-block:: console

  $ npm install -g --prefix=$HOME/local taler-wallet
  # check if installation was successful
  $ taler-wallet-cli --version
  # If this fails, make sure that $HOME/local/bin is in your $PATH

To use the wallet as a library in your own project, run:

.. code-block:: console

  $ npm install taler-wallet


Manual withdrawing
==================

.. code-block:: console

  $ taler-wallet-cli advanced withdraw-manually \
      --exchange https://exchange.eurint.taler.net/ \
      --amount EUR:5

WebExtension Wallet
===================

Building from source
--------------------

.. code-block:: console

  $ git clone https://git.taler.net/wallet-core.git
  $ cd wallet-core
  $ ./configure
  $ make webex-stable
  # Packaged extension now available as:
  # dist/taler-wallet-$VERSION.zip


Android Wallet
==============

Please see :ref:`Build-apps-from-source` in the :doc:`developers-manual`.


APIs and Data Formats
=====================

.. warning::

  These APIs are still a work in progress and *not* final.

Envelope Format
---------------

All API responses and notifications are returned in the
following envelope:

.. ts:def:: WalletResponseEnvelope

   type WalletResponseEnvelope =
    | WalletSuccess
    | WalletError
    | WalletNotification

.. ts:def:: WalletSuccess

   export interface WalletSuccess {
     type: "response";
     operation: string,
     // ID to correlate success response to request
     id: string;
     // Result type depends on operation
     result: unknown;
   }

.. ts:def:: WalletError

   export interface WalletError {
     type: "error";
     operation: string,
     // ID to correlate error response to request
     id: string;
     error: WalletErrorInfo;
   }

.. ts:def:: WalletNotification

   export interface WalletSuccess {
     type: "notification";

     // actual type is WalletNotification,
     // to be documented here
     payload: any;
   }

.. ts:def:: WalletErrorInfo

   export interface WalletErrorInfo {
     // Numeric error code defined defined in the
     // GANA gnu-taler-error-codes registry.
     talerErrorCode: number;

     // English description of the error code.
     talerErrorHint: string;

     // English diagnostic message that can give details
     // for the instance of the error.
     message: string;

     // Error details, type depends
     // on talerErrorCode
     details: unknown;
   }

Balances
--------

Balances are the amounts of digital cash held by the wallet.

:name: ``"getBalances"``
:description: Get a list of balances per currency.
:response:
  .. ts:def:: BalancesResponse

    interface BalancesResponse {
      // a list of balances sorted by currency.
      // (currencies with shorter names first, then lexically ascending).
      //
      // Note: Even when a currency has no balance, but pending or past transactions,
      //       it should be included in this list with a balance of zero.
      balances: Balance[];
    }

  .. ts:def:: Balance

    // Balance for one currency.
    // The currency can be derived from any of the
    // "Amount" fields, as the currency is present even
    // when the amount is zero.
    interface Balance {
      // The total Amount that is currently available to be spent
      // including amounts tied up in ongoing refresh operations. These are hidden from the user.
      // If the user tries to spend coins locked up this way,
      // the wallet will give an error message different from "insufficient balance".
      available: Amount;

      // the total incoming amount that will be added to the available balance
      // when all pending transactions succeed (including internal refreshes)
      pendingIncoming: Amount;

      // the total outgoing amount that will be subtracted from the available balance
      // when all pending transactions succeed (including internal refreshes)
      pendingOutgoing: Amount;

      // true if the balance requires user-interaction, e.g. accepting a tip
      // (DEV: can be left out of a first implementation)
      requiresUserInput: boolean;
    }

Transactions
------------

Transactions are all operations or events that affect the balance.

:Name: ``"getTransactions"``
:Description: Get a list of past and pending transactions.
:Request:
  .. ts:def:: TransactionsRequest

    interface TransactionsRequest {
      // return only transactions in the given currency, if present
      currency?: string;

      // if present, results will be limited to transactions related to the given search string
      search?: string;
    }
:Response:
  .. ts:def:: TransactionsResponse

    interface TransactionsResponse {
      // a list of past and pending transactions sorted by pending, timestamp and transactionId.
      // In case two events are both pending and have the same timestamp,
      // they are sorted by the transactionId
      // (i.e. pending before non-pending transactions, newer before older
      //  and if all equal transactionId lexically ascending).
      transactions: Transaction[];
    }

  .. ts:def:: Transaction

    interface Transaction {
      // opaque unique ID for the transaction, used as a starting point for paginating queries
      // and for invoking actions on the transaction (e.g. deleting/hiding it from the history)
      transactionId: string;

      // the type of the transaction; different types might provide additional information
      type: TransactionType;

      // main timestamp of the transaction
      timestamp: Timestamp;

      // true if the transaction is still pending, false otherwise
      // If a transaction is not longer pending, its timestamp will be updated,
      // but its transactionId will remain unchanged
      pending: boolean;

      // if present, the transaction encountered a fatal error that needs to be shown to the user
      error?: TransactionError;

      // Raw amount of the transaction (exclusive of fees or other extra costs)
      amountRaw: Amount;

      // Amount added or removed from the wallet's balance (including all fees and other costs)
      amountEffective: Amount;
    }

  .. ts:def:: TransactionType

    type TransactionType = (
      TransactionWithdrawal |
      TransactionPayment |
      TransactionRefund |
      TransactionTip |
      TransactionRefresh
    )

  .. ts:def:: TransactionError

   interface TransactionError {
     // TALER_EC_* unique error code.
     // The action(s) offered and message displayed on the transaction item depend on this code.
     ec: number;

     // English-only error hint, if available.
     hint?: string;

     // Error details specific to "ec", if applicable/available
     details?: any;
   }

  .. ts:def:: WithdrawalDetails

    export type WithdrawalDetails =
      | WithdrawalDetailsForManualTransfer
      | WithdrawalDetailsForTalerBankIntegrationApi;

  .. ts:def:: WithdrawalDetailsForManualTransfer

    interface WithdrawalDetailsForManualTransfer {
      type: "manual-transfer";

      // Payto URIs that the exchange supports.
      // Already contains the amount and message.
      exchangePaytoUris: string[];

      // Public key of the newly created reserve.
      // Not useful for the UI, but required for integration testing.
      reservePub: string;
    }

  .. ts:def:: WithdrawalDetailsForTalerBankIntegrationApi

    interface WithdrawalDetailsForTalerBankIntegrationApi {
      type: "taler-bank-integration-api";

      // Set to true if the bank has confirmed the withdrawal, false if not.
      // An unconfirmed withdrawal usually requires user-input and should be highlighted in the UI.
      // See also bankConfirmationUrl below.
      confirmed: boolean;

      // If the withdrawal is unconfirmed, this can include a URL for user
      // initiated confirmation.
      bankConfirmationUrl?: string;
    }

  .. ts:def:: TransactionWithdrawal

    // This should only be used for actual withdrawals
    // and not for tips that have their own transactions type.
    interface TransactionWithdrawal extends Transaction {
      type: string = "withdrawal",

      // Exchange that was withdrawn from.
      exchangeBaseUrl: string;

      // Amount that has been subtracted from the reserve's balance for this withdrawal.
      amountRaw: Amount;

      // Amount that actually was (or will be) added to the wallet's balance.
      // Should always be shown as a positive amount.
      amountEffective: Amount;

      // Further details
      withdrawalDetails: WithdrawalDetails;
    }

  .. ts:def:: TransactionPayment

    interface TransactionPayment extends Transaction {
      type: string = "payment",

      // Additional information about the payment.
      info: OrderShortInfo;

      // Wallet-internal end-to-end identifier for the payment
      // (assigned before the order is even downloaded, thus the name).
      proposalId: string;

      // The current status of this payment.
      status: PaymentStatus;

      // Amount that must be paid for the contract
      amountRaw: Amount;

      // Amount that was paid, including deposit, wire and refresh fees.
      // Should always be shown as a negative amount.
      amountEffective: Amount;
    }

  .. ts:def:: OrderShortInfo

    interface OrderShortInfo {
      // Order ID, uniquely identifies the order within a merchant instance
      orderId: string;

      // More information about the merchant
      merchant: Merchant;

      // Summary of the order, given by the merchant
      summary: string;

      // Map from IETF BCP 47 language tags to localized summaries
      summary_i18n?: { [lang_tag: string]: string };

      // List of products that are part of the order
      products: Product[];

      // URL of the fulfillment, given by the merchant
      fulfillmentUrl?: string;

      // Message shown to the user after the payment is complete.
      fulfillmentMessage?: string;

      // Map from IETF BCP 47 language tags to localized fulfillment messages
      fulfillmentMessage_i18n: { [lang_tag: string]: string };
    }

  .. ts:def:: PaymentStatus

    enum PaymentStatus {
      // Explicitly aborted after timeout / failure
      Aborted = "aborted",

      // Payment failed, wallet will auto-retry.
      // User should be given the option to retry now / abort.
      Failed = "failed",

      // Paid successfully
      Paid = "paid",

      // Only offered, user must accept / decline
      Offered = "offered",

      // User accepted, payment is processing.
      Accepted = "accepted",
    }

  .. ts:def:: TransactionRefund

    interface TransactionRefund extends Transaction {
      type: string = "refund",

      // ID for the transaction that is refunded
      refundedTransactionId: string;

      // Additional information about the refunded payment
      info: OrderShortInfo;

      // Part of the refund that couldn't be applied because the refund permissions were expired
      amountInvalid: Amount;

      // Amount that has been refunded by the merchant.
      // Corresponds to amountRefundGranted from the applyRefund response.
      amountRaw: Amount;

      // Amount will be added to the wallet's balance after fees and refreshing.
      // Should always be shown as a positive amount.
      amountEffective: Amount;
    }

  .. ts:def:: TransactionTip

    interface TransactionTip extends Transaction {
      type: string = "tip",

      // The current status of this tip.
      status: TipStatus;

      // Exchange that the tip will be (or was) withdrawn from
      exchangeBaseUrl: string;

      // More information about the merchant that sent the tip
      merchant: Merchant;

      // Raw amount of the tip, without extra fees that apply
      amountRaw: Amount;

      // Amount will be (or was) added to the wallet's balance after fees and refreshing.
      // Should always be shown as a positive amount.
      amountEffective: Amount;
    }

  .. ts:def:: TipStatus

    enum TipStatus {
      // Only offered, user must accept / decline
      Offered = "offered",

      // User accepted, tip is processing.
      Accepted = "accepted",

      // User declined.
      Declined = "declined",

      // Received successfully
      Received = "received",
    }

  .. ts:def:: TransactionRefresh

    // A transaction shown for refreshes that are not associated to other transactions
    // such as a refresh necessary before coin expiration.
    // It should only be returned by the API if the effective amount is different from zero.
    interface TransactionRefresh extends Transaction {
      type: string = "refresh",

      // Exchange that the coins are refreshed with
      exchangeBaseUrl: string;

      // Raw amount that is refreshed
      amountRaw: Amount;

      // Amount that will be paid as fees for the refresh.
      // Should always be shown as a negative amount.
      amountEffective: Amount;
    }

Refunds
-------

:Name: ``"applyRefund"``
:Description: Process a refund from a ``taler://refund`` URI.
:Request:
  .. ts:def:: WalletApplyRefundRequest

    interface WalletApplyRefundRequest {
      talerRefundUri: string;
    }
:Response:
  .. ts:def:: WalletApplyRefundResponse

    interface WalletApplyRefundResponse {
      // Identifier for the purchase that was refunded
      // DEPRECATED:  Will disappear soon.
      contractTermsHash: string;

      amountEffectivePaid: Amount;

      amountRefundGranted: Amount;

      amountRefundGone: Amount;

      pendingAtExchange: boolean;

      // Short info about the order being refunded.
      info: OrderShortInfo;
    }

Exchange Management
-------------------

List Exchanges
~~~~~~~~~~~~~~

:Name: ``"listExchanges"``
:Description:
  List all exchanges.
:Response:
  .. ts:def:: ExchangesListResponse

    interface ExchangesListResponse {
      exchanges: ExchangeListItem[];
    }

  .. ts:def:: ExchangeListItem

    interface ExchangeListItem {
      exchangeBaseUrl: string;
      currency: string;
      paytoUris: string[];
    }

Add Exchange
~~~~~~~~~~~~

:Name: ``"addExchange"``
:Description:
  Add an exchange.
:Request:
  .. ts:def:: ExchangeAddRequest

    interface ExchangeAddRequest {
      exchangeBaseUrl: string;
    }
:Response:
  On success, the response is an `ExchangeListItem`.


Force Exchange Update
~~~~~~~~~~~~~~~~~~~~~

:Name: ``"forceUpdateExchange"``
:Description:
  Force updating an exchange.
  Re-queries current cryptographic key material, wire information
  and terms of service from the exchange.  Also applies denomination revocations
  if applicable.
:Request:
  .. ts:def:: ExchangeForceUpdateRequest

    interface ExchangeForceUpdateRequest {
      exchangeBaseUrl: string;
    }
:Response:
  On success, the response is an `ExchangeListItem`.


Get Terms of Service
~~~~~~~~~~~~~~~~~~~~

:Name: ``"getExchangeTos"``
:Description:
  Get the exchange's current ToS and which version of the ToS (if any)
  the user has accepted.
:Request:
  .. ts:def:: ExchangeGetTosRequest

    interface ExchangeGetTosRequest {
      exchangeBaseUrl: string;
    }
:Response:
  .. ts:def:: ExchangeGetTosResult

    interface GetExchangeTosResult {
      // Markdown version of the current ToS.
      tos: string;

      // Version tag of the current ToS.
      currentEtag: string;

      // Version tag of the last ToS that the user has accepted,
      // if any.
      acceptedEtag: string | undefined;
    }

Set Accepted Terms of Service Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Name: ``"setExchangeTosAccepted"``
:Description:
  Store that the user has accepted a version of the exchange's ToS.
:Request:
  .. ts:def:: ExchangeSetTosAccepted

    interface ExchangeGetTosRequest {
      exchangeBaseUrl: string;
      acceptedEtag: string;
    }
:Response:
  On success, the response is an empty object.


Withdrawal
----------

A typical API sequence for *bank-integrated* withdrawals can for example look like this:

#. ``"getWithdrawalDetailsForUri"`` returns an amount and default exchange
#. ``"getWithdrawalDetailsForAmount"`` returns fee information and that ToS are not accepted

   #. ``"getExchangeTos"`` are shown to the user and return currentEtag
   #. ``"setExchangeTosAccepted"`` called with currentEtag after user accepted

#. ``"acceptWithdrawal"`` after the user confirmed withdrawal with associated fees

A typical API sequence for *manual* withdrawals can for example look like this:

#. ``"listExchanges"`` shows a list of exchanges to the user who picks one and an amount
#. ``"getWithdrawalDetailsForAmount"`` returns fee information and that ToS are not accepted

   #. ``"getExchangeTos"`` are shown to the user and return currentEtag
   #. ``"setExchangeTosAccepted"`` called with currentEtag after user accepted

#. ``"acceptManualWithdrawal"`` after the user confirmed withdrawal with associated fees

Get Details For Bank-integrated Withdrawal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Name: ``"getWithdrawalDetailsForUri"``
:Description:
  Get information about exchanges for a bank-integrated withdrawal from a ``taler://withdraw`` URI.
:Request:
  .. ts:def:: GetWithdrawalUriDetailsRequest

    interface GetWithdrawalUriDetailsRequest {
      talerWithdrawUri: string;
    }
:Response:
  .. ts:def:: WithdrawalDetailsForUri

    interface WithdrawalDetailsForUri {
      // The amount that the user wants to withdraw
      amount: Amount;

      // Exchange suggested by the wallet
      defaultExchangeBaseUrl?: string;

      // A list of exchanges that can be used for this withdrawal
      possibleExchanges: ExchangeListItem[];
    }

Get Withdrawal Details
~~~~~~~~~~~~~~~~~~~~~~

:Name: ``"getWithdrawalDetailsForAmount"``
:Description:
  Get information about fees and exchange for a withdrawal of a given amount.
  Can be used for both bank-integrated and manual withdrawals.
:Request:
  .. ts:def:: WithdrawalDetailsRequest

    interface WithdrawalDetailsRequest {
      exchangeBaseUrl: string;
      amount: Amount;
    }
:Response:
  .. ts:def:: WithdrawalDetails

    interface WithdrawalDetails {
      // Did the user accept the current version of the exchange's terms of service?
      tosAccepted: boolean;

      // Amount that will be transferred to the exchange.
      amountRaw: Amount;

      // Amount that will be added to the user's wallet balance.
      amountEffective: Amount;
    }

Accept Bank-integrated Withdrawal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Name: ``"acceptWithdrawal"``
:Description:
  Accept a bank-integrated withdrawal, where the bank transfers funds automatically.
:Request:
  .. ts:def:: GetManualWithdrawalDetailsRequest

    interface AcceptWithdrawalRequest {
      talerWithdrawUri: string;
      exchangeBaseUrl: string;
    }
:Response:
  .. ts:def:: AcceptWithdrawalResponse

    interface AcceptWithdrawalResponse {
      // a URL for user initiated confirmation.
      bankConfirmationUrl?: string;
    }

Accept Manual Withdrawal
~~~~~~~~~~~~~~~~~~~~~~~~

:Name: ``"acceptManualWithdrawal"``
:Description:
  Accept a manual withdrawal, where the user has to transfer funds manually.
:Request:
  .. ts:def:: AcceptManualWithdrawalRequest

    interface AcceptManualWithdrawalRequest {
      exchangeBaseUrl: string;
      amount: Amount;
    }
:Response:
  .. ts:def:: AcceptManualWithdrawalResponse

    interface AcceptManualWithdrawalResponse {
      // Payto URIs to fund the withdrawal,
      // with amount and message provided.
      exchangePaytoUris: string[];
    }

Payments
--------

Prepare Pay
~~~~~~~~~~~

:Name: ``"preparePay"``
:Description:
  Fetch information about a payment request from a merchant.
:Request:
  .. ts:def:: PreparePayRequest

    interface PreparePayRequest {
      talerPayUri: string;
    }
:Response:
  .. ts:def:: PreparePayResponse

    type PreparePayResponse =
      | PreparePayPaymentPossibleResponse
      | PreparePayAlreadyConfirmedResponse
      | PreparePayInsufficientBalanceResponse;

  .. ts:def:: PreparePayPaymentPossibleResponse

    interface PreparePayPaymentPossibleResponse {
      status: "payment-possible";

      proposalId: string;

      // Verbatim contract terms as generated by the merchant.
      contractTerms: ContractTerms;

      // Amount that the merchant is asking for.
      amountRaw: Amount;

      // Amount that will effectively be subtracted from the wallet's
      // balance when accepting this proposal.
      amountEffective: Amount;
    }

  .. ts:def:: PreparePayInsufficientBalanceResponse

    interface PreparePayInsufficientBalanceResponse {
      status: "insufficient-balance";

      proposalId: string;

      // Amount that the merchant is asking for.
      amountRaw: Amount;

      // Verbatim contract terms as generated by the merchant.
      contractTerms: ContractTerms;
    }

  .. ts:def:: PreparePayAlreadyConfirmedResponse

    interface PreparePayAlreadyConfirmedResponse {
      status: "already-confirmed";

      proposalId: string;

      // Did the payment succeed?
      paid: boolean;

      // Amount that the merchant is asking for.
      amountRaw: Amount;

      // Amount that will be subtracted from the wallet balance
      amountEffective: Amount;

      // Verbatim contract terms as generated by the merchant.
      contractTerms: ContractTerms;
    }


Confirm Payment
~~~~~~~~~~~~~~~

:Name: ``"confirmPay"``
:Description:
  Confirm making a payment.

:Request:
  .. ts:def:: GetManualWithdrawalDetailsRequest

    interface ConfirmPayRequest {
      proposalId: string;
    }
:Response:
  .. ts:def:: ConfirmPayResultDone

    interface ConfirmPayResultDone {
      type: "done";

      contractTerms: ContractTerms;
    }

  .. ts:def:: ConfirmPayResultPending

    // Payment was marked as confirmed,
    // but the attempt(s) to pay were not successful yet.
    interface ConfirmPayPending {
      type: "pending";

      lastError: TransactionError;
    }

  .. ts:def:: ConfirmPayResult

    type ConfirmPayResult =
      | ConfirmPayResultDone;
      | ConfirmPayResultPending;

Abort Failed Payment
~~~~~~~~~~~~~~~~~~~~

:Name: ``"abortFailedPayWithRefund"``
:Description:
  Abort a failed payment and try to get a refund for the
  partially paid amount.
:Request:
  .. ts:def:: AbortPayWithRefundRequest

    export interface AbortPayWithRefundRequest {
      proposalId: string;
    }
:Response:
  On success, the response is an empty object.

Tipping API Calls
-----------------

Preparing a tip
~~~~~~~~~~~~~~~

:Name: ``"prepareTip"``
:Description:
  Prepare to accept a tip based in a ``taler://tip`` URI.
:Request:
  .. ts:def:: PrepareTipRequest

    interface PrepareTipRequest {
      talerTipUri: string;
    }
:Response:
  .. ts:def:: PrepareTipResult

    interface PrepareTipResult {
      // Unique ID for the tip assigned by the wallet.
      // Typically different from the merchant-generated tip ID.
      walletTipId: string;

      // Has the tip already been accepted?
      accepted: boolean;
      tipAmountRaw: AmountString;
      tipAmountEffective: AmountString;
      exchangeBaseUrl: string;
      expirationTimestamp: Timestamp;
    }


Accepting a tip
~~~~~~~~~~~~~~~

:Name: ``"acceptTip"``
:Description:
  Prepare to accept a tip based in a ``taler://tip`` URI.
:Request:
  .. ts:def:: AcceptTipRequest

    interface AcceptTipRequest {
      walletTipId: string;
    }
:Response:
  On success, the response is an empty object.

Testing API calls
-----------------

The following API calls are useful for testing.

Withdraw balance from the TESTKUDOS environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Name: ``"withdrawTestkudos"``
:Description:
  Withdraw a balance from the ``TESTKUDOS`` environment.
:Request:
  The request parameters are ignored.
:Response:
  On success, the response is an empty object.

Withdraw balance from a test environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Name: ``"withdrawTestBalance"``
:Description:
  Withdraw a balance from a test environment.
:Request:
  .. ts:def:: WithdrawTestBalanceRequest

    interface WithdrawTestBalanceRequest {
      amount: string;
      bankBaseUrl: string;
      exchangeBaseUrl: string;
    }
:Response:
  On success, the response is an empty object.

Run integration test
~~~~~~~~~~~~~~~~~~~~

:Name: ``"runIntegrationTest"``
:Description:
  Run a basic integration test that does a withdrawal, payment,
  refund and again a payment.  Useful to generate test data
  in the integration tests of other components.
:Request:
  .. ts:def:: IntegrationTestArgs

    interface IntegrationTestArgs {
      exchangeBaseUrl: string;
      bankBaseUrl: string;
      merchantBaseUrl: string;
      merchantApiKey: string;
      amountToWithdraw: string;
      amountToSpend: string;
    }
:Response:
  On success, the response is an empty object.

Make a test payment
~~~~~~~~~~~~~~~~~~~

:Name: ``"testPay"``
:Description:
  Make a test payment with existing funds.
:Request:
  .. ts:def:: TestPayArgs

    interface TestPayArgs {
      merchantBaseUrl: string;
      merchantApiKey: string;
      amount: string;
      summary: string;
    }


Dump all coins to JSON
~~~~~~~~~~~~~~~~~~~~~~

:Name: ``"dumpCoins"``
:Description:
  Make a test payment with existing funds.
:Request:
  The request object is ignored.
:Response:
  .. code:: ts

    interface CoinDumpJson {
      coins: Array<{
        /**
         * The coin's denomination's public key.
         */
        denom_pub: string;
        /**
         * Hash of denom_pub.
         */
        denom_pub_hash: string;
        /**
         * Value of the denomination (without any fees).
         */
        denom_value: string;
        /**
         * Public key of the coin.
         */
        coin_pub: string;
        /**
         * Base URL of the exchange for the coin.
         */
        exchange_base_url: string;
        /**
         * Remaining value on the coin, to the knowledge of
         * the wallet.
         */
        remaining_value: string;
        /**
         * Public key of the parent coin.
         * Only present if this coin was obtained via refreshing.
         */
        refresh_parent_coin_pub: string | undefined;
        /**
         * Public key of the reserve for this coin.
         * Only present if this coin was obtained via refreshing.
         */
        withdrawal_reserve_pub: string | undefined;
        /**
         * Is the coin suspended?
         * Suspended coins are not considered for payments.
         */
        coin_suspended: boolean;
      }>;
    }


Suspend/unsuspend a coin
~~~~~~~~~~~~~~~~~~~~~~~~

A suspended coin will not be used by the wallet for payments.
This functionality is only used for testing.

:Name: ``"setCoinSuspended"``
:Description:
  Make a test payment with existing funds.
:Request:
  .. ts:def:: SetCoinSuspendedRequest

    interface SetCoinSuspendedRequest {
      coinPub: string;
      suspended: boolean;
    }
:Request:
  On success, the response is an empty object.

Global Errors
-------------

* Backup/Sync/Anastasis failed
* refresh after pay failed for multiple attempts
  (depending on online status)
* scheduled refresh (to avoid expiration) failed
* general recoups (?)
* failed recoup
* (maybe) fatal errors during withdrawal
* pending refund failed permanently (?)

Integration Tests
=================

Integration Test Example
------------------------

Integration tests can be done with the low-level wallet commands.  To select which coins and denominations
to use, the wallet can dump the coins in an easy-to-process format (`CoinDumpJson <https://git.taler.net/wallet-core.git/tree/src/types/talerTypes.ts#n734>`__).

The database file for the wallet can be selected with the ``--wallet-db``
option.  This option must be passed to the ``taler-wallet-cli`` command and not
the subcommands.  If the database file doesn't exist, it will be created.

The following example does a simple withdrawal recoup:

.. code-block:: console

  # Withdraw digital cash
  $ taler-wallet-cli --wallet-db=mydb.json testing withdraw \
      -b https://bank.int.taler.net/ \
      -e https://exchange.int.taler.net/ \
      -a INTKUDOS:10

  $ coins=$(taler-wallet-cli --wallet-db=mydb.json advanced dump-coins)

  # Find coin we want to revoke
  $ rc=$(echo "$coins" | \
         jq -r '[.coins[] | select((.denom_value == "INTKUDOS:5"))][0] | .coin_pub')

  # Find the denom
  $ rd=$(echo "$coins" | \
         jq -r '[.coins[] | select((.denom_value == "INTKUDOS:5"))][0] | .denom_pub_hash')

  # Find all other coins, which will be suspended
  $ susp=$(echo "$coins" | \
           jq --arg rc "$rc" '[.coins[] | select(.coin_pub != $rc) | .coin_pub]')

  # The exchange revokes the denom
  $ taler-exchange-keyup -r $rd
  $ taler-deployment-restart

  # Now we suspend the other coins, so later we will pay with the recouped coin
  $ taler-wallet-cli --wallet-db=mydb.json advanced suspend-coins "$susp"

  # Update exchange /keys so recoup gets scheduled
  $ taler-wallet-cli --wallet-db=mydb.json exchanges update -f https://exchange.int.taler.net/

  # Block until scheduled operations are done
  $ taler-wallet-cli --wallet-db=mydb.json run-until-done

  # Now we buy something, only the coins resulting from recouped will be
  # used, as other ones are suspended
  $ taler-wallet-cli --wallet-db=mydb.json testing test-pay \
      -m https://backend.int.taler.net/ \
      -k sandbox \
      -a "INTKUDOS:1" \
      -s "foo"
  $ taler-wallet-cli --wallet-db=mydb.json run-until-done


To test refreshing, force a refresh:

.. code-block:: console

  $ taler-wallet-cli --wallet-db=mydb.json advanced force-refresh "$coin_pub"


To test zombie coins, use the timetravel option. It **must** be passed to the
top-level command and not the subcommand:

.. code-block:: console

  # Update exchange /keys with time travel, value in microseconds
  $ taler-wallet-cli --timetravel=1000000 --wallet-db=mydb.json \
      exchanges update -f https://exchange.int.taler.net/

Test Cases
----------

Things we already have tests for:

* Can the wallet recoup coins and spend them?
  [`link <https://git.taler.net/wallet-core.git/tree/integrationtests/test-recoup.sh>`__]

Things we still need tests for:

* Does the wallet do retries correctly when the exchange is not reachable?
  Or when the merchant is not reachable?  Or the bank?
  This can be tested by temporarily killing those services.
* How does the wallet deal with processing the same ``taler://(pay|withdraw)`` URI twice?
* Test tipping (accepting/refusing a tip)
* Test refunds
* Test for :ref:`session-based payments <repurchase>`
* Test case for auto-refunds
  (scenario where the vending machine finds out that its motor is broken,
  so it automatically gives a refund)
* Does the wallet report "insufficient balance" correctly
  (as opposed to, say, crashing)?
* Perf tests:  How does the wallet handle withdrawing a *LOT* of coins?
* Are the transaction history and pending operations reported correctly?

Tests for things the wallet doesn't handle correctly yet:

* What happens if the wallet double-spends a coin?
  (Easy to test by copying the wallet DB before spending
  and then running a spend again with the old DB).
* What happens when a reserve is changed between accepting withdrawal
  and actually withdrawing coins?
  (This is harder to test.  Might not be possible with the current CLI.
  The idea would be be to have some ``--inhibit=withdraw`` flag
  that tells the wallet to not actually withdraw,
  so we can change the reserve state and then resume the wallet.)
* What happens if the exchange suddenly has a completely new list of denominations on offer?
* What happens if the exchange changes its master public key?
  The wallet *should* handle this gracefully
  even if we have coins with that exchange,
  provided that the old denominations can be recouped.
  (That one is pretty difficult!)
* Does the wallet handle :ref:`payment aborts <order-abort>` correctly?

There are test cases that require us to modify the communication between the wallet and exchange.

* What does the wallet do when the exchange/merchant announce an incompatible protocol version?
* What happens if some signature made by the exchange/merchant is garbage?
* What if the exchange reports a double-spend and the proof it gives us is invalid?



Integration Test and Fault Injection Framework
----------------------------------------------

This section describes the current approach to integration testing in the wallet.

It's all based on a TypeScript harness process, which itself implements
the fault injection proxy (async and in-process)!

The new approach consists of the following parts:

1. A strongly typed, convenient helper library to easily set up and run
arbitrary Taler deployments and run test cases.  These components plug
together as easily as lego bricks, even with multiple
exchanges/merchants/banks/etc.  Logs and clean shutdown (even on SIGINT
or errors) are handled properly.  (Support for auditors is still pending
but needed to fully test the wallet.)

This is how a simple withdrawal and payment test case looks like:
`<https://git.taler.net/wallet-core.git/tree/packages/taler-integrationtests/src/test-payment.ts>`__

(What's particularly nice is that all our docs contain TypeScript
definitions for all API request bodies.  So just copying them into the
test harness gives us auto-completion and compile-time checks to avoid
typos.  The wallet's JSON validation machinery is also re-used.)

2. A fault injection proxy that can be plugged between the services
and/or the wallet.  It runs alongside the test harness, and can thus can
use arbitrary custom logic.  There's no dependency for it other than
built-in Node.JS libraries.  Simple fault injections are just as easy to
set up as with the twister.

The following test case (a) logs all requests and responses to the test
harness stdout and (b) at a certain point, starts dropping the next 10
requests to the exchange (testing the wallet's retry logic):

`<https://git.taler.net/wallet-core.git/tree/packages/taler-integrationtests/src/test-payment-fault.ts#n165>`__

3. All util functionality from JS wallet-core, such as the Taler crypto,
amount/date/etc. handling and JSON parsing/validation (the wallet is now
more modular and easier to use as a library) can be used in the
integration tests, even if a different wallet (Kotlin, whatever) is
tested via the CLI.

4. A bunch of test cases that use (1)-(3).  These are *significantly*
more readable and hackable than other test approaches we had, while
allowing for more complex scenarios.  There are still way too few tests
though!

5. A test runner (written in bash) that runs test cases based on a glob
pattern and reports the results.

Injecting a fault is as easy as:

.. code:: ts

  // Set up test case
  [...]

  exchangeProxy.addFault({
    beforeResponse(ctx: FaultInjectionResponseContext) {
       if (cond1) { // Drop some responses
         ctx.dropResponse = true;
         return;
       } else if (cond2) { // modify some others
         ctx.responseBody = Buffer.from(`{"oops": true}`, "utf-8");
         return;
       }
       // Other things that can be modified:
       // - drop/modify the request, not just the response
       // - modify headers
       // - modify status codes
    }
  });

  await doSomethingWithTheWallet();

  exchangeProxy.clearFault();

  await doMoreWithTheWallet();


To make the configuration easy, an ``ExchangeService`` (or ``MerchantService``,
``BankService`` etc.) can be wrapped in a ``FaultInjectedExchangeService``,
which implements the ``ExchangeServiceInterface``:

.. code:: ts

  // create exchange and two merchants
  const exchange = await setupExchange(...);
  const merchant1 = ...;
  const merchant2 = ...;

  // Add exchange to merchant-accepted exchanges.
  // This will adjust the config.
  merchant1.addExchange(exchange);

  // Wrap exchange in fault injection proxy
  const faultInjectedExchange: ExchangeServiceInterface
    = new FaultInjectedExchangeService(t, exchange1, 8085);

  // Merchant 2 talks to the exchange over fault injection,
  // and thus must use the "twisted" base URL.
  merchant2.addExchange(faultInjectedExchange);


The package for the integration tests is here:

`<https://git.taler.net/wallet-core.git/tree/packages/taler-integrationtests>`__

The shortcut to run all integration tests is

.. code:: sh

  ./bootstrap && ./configure --prefix=... \
     && make install integrationtests

(From the root of the whole repo.  If you're developing tests, it's way
faster to just run "make compile install" once and then use
"./testrunner" from the ``taler-integrationtests`` package.)