[GNUnet-SVN] [taler-docs] branch master updated (ca693f4 -> 47adf02)

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a change to branch master
in repository docs.

    from ca693f4  Workers.
     new 329eeb6  reflow
     new 47adf02  docs (wallet, nfc)

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 index.rst                       |   1 +
 taler-bank-manual.rst           |   4 +-
 taler-merchant-api-tutorial.rst |   8 +--
 taler-merchant-manual.rst       |   2 +-
 taler-nfc-guide.rst             | 113 ++++++++++++++++++++++++++++------------
 taler-wallet.rst                |  74 ++++++++++++++++++++++++++
 6 files changed, 159 insertions(+), 43 deletions(-)
 create mode 100644 taler-wallet.rst

diff --git a/index.rst b/index.rst
index 060795f..8548e52 100644
--- a/index.rst
+++ b/index.rst
@@ -53,6 +53,7 @@ Documentation Overview
   core/index
   taler-exchange-manual
   taler-merchant-manual
+  taler-wallet
   taler-nfc-guide.rst
   taler-merchant-api-tutorial
   taler-bank-manual
diff --git a/taler-bank-manual.rst b/taler-bank-manual.rst
index c85e0aa..4c1b573 100644
--- a/taler-bank-manual.rst
+++ b/taler-bank-manual.rst
@@ -1,5 +1,5 @@
-The GNU Taler bank manual
-#########################
+GNU Taler bank manual
+#####################
 
 Introduction
 ============
diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst
index 2981e43..bfae7f0 100644
--- a/taler-merchant-api-tutorial.rst
+++ b/taler-merchant-api-tutorial.rst
@@ -1,4 +1,4 @@
-The GNU Taler Merchant API Tutorial
+GNU Taler Merchant API Tutorial
 ###################################
 
 Introduction
@@ -27,8 +27,6 @@ This version of the tutorial has examples for Python3. It 
uses the
 requests library for HTTP requests. Versions for other
 languages/environments are available as well.
 
-examples
-git
 If you want to look at some simple, running examples, check out these:
 
 -  The `essay
@@ -346,7 +344,6 @@ Advanced topics
 Detecting the Presence of the Taler Wallet
 ------------------------------------------
 
-wallet
 Taler offers ways to detect whether a user has the wallet installed in
 their browser. This allows Web sites to adapt accordingly. Note that not
 all platforms can do presence detection reliably. Some platforms might
@@ -504,9 +501,6 @@ previous payment.
 The Taler Order Format
 ----------------------
 
-contract
-terms
-order
 A Taler order can specify many details about the payment. This section
 describes each of the fields in depth.
 
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index d668de3..1dfbfc7 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -1,5 +1,5 @@
 GNU Taler Merchant Backend Operator Manual
-##############################################
+##########################################
 
 Introduction
 ============
diff --git a/taler-nfc-guide.rst b/taler-nfc-guide.rst
index a5be51a..029b84f 100644
--- a/taler-nfc-guide.rst
+++ b/taler-nfc-guide.rst
@@ -1,7 +1,8 @@
 GNU Taler NFC Guide
 ###################
 
-This guide explains how NFC (near-field communication) is used in the GNU 
Taler payment system.
+This guide explains how NFC (near-field communication) is
+used in the GNU Taler payment system.
 
 Introduction
 ============
@@ -11,8 +12,8 @@ NFC is currently used for two different purposes:
 1. Operations in the wallet (payment, withdrawal, ...) can be triggered by a
    merchant PoS (Point-of-Sale) terminal or Taler-capable ATM.
 2. When either the wallet or the merchant do not have Internet connectivity,
-   the protocol messages to the exchange or merchant backend service can be 
tunneled via NFC
-   through the party that has Internet connectivity.
+   the protocol messages to the exchange or merchant backend service can be
+   tunneled via NFC through the party that has Internet connectivity.
 
 
 Background: Payment Processing with GNU Taler
@@ -22,14 +23,33 @@ The following steps show a simple payment process with GNU 
Taler.  Examples are
 written in `Bash <https://www.gnu.org/software/bash/>`_ syntax,
 using `curl <https://curl.haxx.se/docs/manpage.html>`_ to make HTTP(S) 
requests.
 
-1. The merchant creates an *order*, which contains the details of the payment 
and the product/service
-   that the customer will receive.
+
+1. The merchant creates an *order*, which contains the details of the payment
+   and the product/service that the customer will receive.
    An order is identified by an alphanumeric *order ID*.
-   
-   The following :http:post:`/order` request to the merchant backend creates a 
simple order:
+
+   The *fulfillment URL* is an URL that the wallet will redirect the customer
+   to once the payment is complete.  For digital products, this is typically an
+   ``https(s)://`` URL that renders the purchased content.  For physical
+   products and in-store purchases, a ``taler://fulfillment-success/<message>``
+   URL should be specified instead.  The wallet will display the URL-encoded
+   UTF-8 text ``<message>`` when the payment has succeeded.
+
+   .. hint::
+
+     When an ``http(s)://`` URL is used as the fulfillment URL in an in-store 
/ NFC payment,
+     the user might not be able to view the page, as request tunneling only 
works for requests
+     made by the wallet to the merchant backend / exchange.
+
+     In these situations, wallets should display to the user that a page to 
view the purchase
+     can be opened, and give a warning if it is detected that the devices does 
not have Internet
+     connectivity.
+
+   The following :http:post:`/order` request to the merchant backend creates a
+   simple order:
 
    .. code-block:: sh
- 
+
     $ backend_base_url=https://backend.demo.taler.net/
     $ auth_header='Authorization: ApiKey sandbox'
     $ order_req=$(cat <<EOF
@@ -48,10 +68,11 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to 
make HTTP(S) requests.
       "order_id": "2019.255-02YDHMXCBQP6J"
     }
 
-2. The merchant checks the payment status of the order using 
:http:get:`/check-payment`:
+2. The merchant checks the payment status of the order using
+   :http:get:`/check-payment`:
 
    .. code-block:: sh
- 
+
      $ backend_base_url=https://backend.demo.taler.net/
      $ auth_header='Authorization: ApiKey sandbox'
      $ curl -XGET -H"$auth_header" \
@@ -73,7 +94,8 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to 
make HTTP(S) requests.
 
    The details of ``taler://`` URIs are specified :ref:`here 
<taler-uri-scheme>`.
 
-3. The wallet processes the ``taler://pay/`` URI.  In this example, we use the 
command line wallet:
+3. The wallet processes the ``taler://pay/`` URI.  In this example, we use the
+   command-line wallet:
 
    .. code-block:: sh
 
@@ -86,10 +108,16 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to 
make HTTP(S) requests.
      $ taler-wallet-cli pay-uri 
'taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J'
      # [... User is asked to confirm the payment ...]
 
+   .. hint::
+
+     The command-line wallet is typically used by developers and not by 
end-users.
+     See the :ref:`wallet manual <command-line-wallet>` for installation 
instructions.
+
+
 4. The merchant checks the payment status again:
 
    .. code-block:: sh
- 
+
      $ backend_base_url=https://backend.demo.taler.net/
      $ auth_header='Authorization: ApiKey sandbox'
      $ curl -XGET -H"$auth_header" \
@@ -100,6 +128,16 @@ using `curl <https://curl.haxx.se/docs/manpage.html>`_ to 
make HTTP(S) requests.
        # ... (some fields omitted)
      }
 
+   .. note::
+
+     When paying for digital products displayed on a Web site identified by the
+     fulfillment URL, the merchant only needs to check the payment status
+     before responding with the fulfillment page.
+
+     For in-store payments, the merchant must periodically check the payment 
status.
+     Instead of polling in a busy loop, the ``long_poll_ms`` parameter of 
:http:get:`/check-payment`
+     should be used.
+
 
 Taler NFC Basics
 ================
@@ -115,17 +153,22 @@ and commands defined in `ISO 7816 
<https://cardwerk.com/iso-7816-smart-card-stan
 
 The GNU Taler wallet uses the AID (application identifier) ``F00054414c4552``.
 The ``F`` prefix indicates the proprietary/unregistered namespace of AIDs, and
-the rest of the identifier is the hex-encoded ASCII-string ``TALER`` (with one 
0-byte left padding).
+the rest of the identifier is the hex-encoded ASCII-string ``TALER`` (with one
+0-byte left padding).
 
-During the time that the wallet is paired with a reader, there is state 
associated with the communication channel.
-Most importantly, the first message sent by the reader to the wallet must be a 
``SELECT FILE (=0xA4)`` that selects
-the GNU Taler AID.  Messages that are sent before the correct ``SELECT FILE`` 
message result in undefined behavior.
+During the time that the wallet is paired with a reader, there is state
+associated with the communication channel. Most importantly, the first message
+sent by the reader to the wallet must be a ``SELECT FILE (=0xA4)`` that selects
+the GNU Taler AID.  Messages that are sent before the correct ``SELECT FILE``
+message results in implementation-defined behavior, such as the tag 
disconnecting,
+ignoring the message or an app other than the wallet receiving the message.
 
-The reader sends commands to the wallet with the ``PUT DATA (=0xDA)`` 
instruction, using the instruction parameters ``0x0100``,
-denoting a proprietary instruction.
+The reader sends commands to the wallet with the ``PUT DATA (=0xDA)``
+instruction, using the instruction parameters ``0x0100``, denoting a
+proprietary instruction.
 
-The command data of the ``PUT DATA`` APDU is prefixed by a one-byte Taler 
instruction ID (TID).  Currently, the following TIDs
-are used:
+The command data of the ``PUT DATA`` APDU is prefixed by a one-byte Taler
+instruction ID (TID).  Currently, the following TIDs are used:
 
 .. list-table::
   :widths: 5 50
@@ -139,19 +182,23 @@ are used:
     - Accept the UTF-8 encoded JSON object in the remainder of the command 
data as a request tunneling response.
 
 
-The ``GET DATA (=0xCA)`` instruction (again with the instruction parameters 
``0x0100``) is used to request
-a command from the wallet.  The APDU with this instruction must be sent with a 
``0x0000`` trailer to indicate
-that up to 65536 bytes of data are expected in the response from the wallet.  
Note that the wallet itself cannot
-initiate communication, and thus the reader must "poll" the wallet for 
commands.
+The ``GET DATA (=0xCA)`` instruction (again with the instruction parameters
+``0x0100`` is used to request a command from the wallet.  The APDU with this
+instruction must be sent with a ``0x0000`` trailer to indicate that up to 65536
+bytes of data are expected in the response from the wallet.  Note that the
+wallet itself cannot initiate communication, and thus the reader must "poll"
+the wallet for commands.
 
-The response to the ``GET DATA`` instruction has a Taler instruction ID in the 
first byte.  The rest of the
+The response to the ``GET DATA`` instruction has a Taler instruction ID in the
+first byte.  The rest of the
 body is interpreted depending on the TID.
 
 .. list-table::
-  :widths: 5 50
+  :widths: 15 50
   :header-rows: 1
 
-  * - TID (wallet to reader)
+  * - TID
+      (wallet to reader)
     - Description
   * - ``0x03``
     - Accept the UTF-8 encoded JSON object in the remainder of the command 
data as a request tunneling request.
@@ -165,10 +212,10 @@ terminal sends a ``SELECT FILE`` command with the GNU 
Taler AID, and a ``PUT
 DATA`` command with TID ``0x01`` and the URI in the rest
 of the command data.
 
-Here is an example protocol trace from an interaction which caused the wallet 
to dereference
-the ``taler://pay/`` URI from the example above:
+Here is an example protocol trace from an interaction which caused the wallet
+to dereference the ``taler://pay`` URI from the example above:
 
-.. code:: none
+.. code-block:: none
 
   # SELECT FILE
   m->w 00A4040007F00054414c4552
@@ -189,8 +236,8 @@ terminal or "tipping provider".)
 Request tunneling
 =================
 
-Request tunneling allows tunneling a (very) restricted subset of HTTP through 
NFC.
-In particular, only JSON request and response bodies are allowed.
+Request tunneling allows tunneling a (very) restricted subset of HTTP through
+NFC. In particular, only JSON request and response bodies are allowed.
 
 It is currently assumed that the requests and responses fit into one APDU 
frame.
 For devices with more limited maximum APDU sizes, additional TIDs for segmented
@@ -217,7 +264,7 @@ The request tunneling request/response JSON messages have 
the following schema:
     // Request headers
     headers?: { [name: string]: string };
 
-    // JSON body for the request, only applicable to GET requests
+    // JSON body for the request, only applicable to POST requests
     body?: object;
   }
 
diff --git a/taler-wallet.rst b/taler-wallet.rst
new file mode 100644
index 0000000..50bf0ef
--- /dev/null
+++ b/taler-wallet.rst
@@ -0,0 +1,74 @@
+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
+  $ 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
+==============
+
+*TODO*
+

-- 
To stop receiving notification emails like this one, please contact
address@hidden.