summaryrefslogtreecommitdiff
path: root/taler-wallet.rst
blob: 8c2d7ebaf20834c1e4e6786e5293509bd35aed84 (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
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:: sh

  $ git clone https://git.taler.net/wallet-core.git
  $ ./bootstrap
  $ cd wallet-core
  $ ./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:: sh

  $ 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:: sh

  $ 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:: sh

  $ npm install taler-wallet


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

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

.. code-block:: sh

  $ 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
==============

*TBD.*


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

.. warning::

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

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

Transactions are all operations or events that are affecting the balance.

:name: ``"transactions"``
:description: Get a list of past and pending transactions.
:request:
  .. ts:def:: TransactionsRequest

    interface TransactionsRequest {
      // return only transactions in the given currency
      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
      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
      pending: boolean;
    }

  .. ts:def:: TransactionType

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

  .. 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;

      // 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;

      // 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.
      amountEffective: Amount;
    }

  .. ts:def:: TransactionPayment

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

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

      // Amount that was paid, including deposit, wire and refresh fees.
      amountEffective: Amount;
    }

  .. ts:def:: TransactionInfo

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

      // More information about the merchant
      merchant: Merchant;

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

      // 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;
    }

  .. ts:def:: TransactionRefund

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

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

      // 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
      amountRaw: Amount;

      // Amount will be added to the wallet's balance after fees and refreshing
      amountEffective: Amount;
    }

  .. ts:def:: TransactionTip

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

      // true if the user still needs to accept/decline this tip
      waiting: boolean;

      // true if the user has accepted this top, false otherwise
      accepted: boolean;

      // 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
      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
      contractTermsHash: string;
    }


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:: sh

  # 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:: sh

  $ 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:: sh

  # 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/