Merge branch 'master' of git+ssh://git.taler.net/exchange

3 files changed, 242 insertions, 232 deletions

diff --git a/doc/flows/main.de.tex b/doc/flows/main.de.tex
new file mode 100644
index 000000000..88fc3fac1
--- /dev/null
+++ b/doc/flows/main.de.tex
@@ -0,0 +1,239 @@
+% This is a (partial) translation of main.tex into
+% German. Please keep the structure as parallel as
+% possible when improving / expanding the translation!
+\documentclass[10pt,a4paper,oneside]{book}
+\usepackage[utf8]{inputenc}
+\usepackage{url}
+\usepackage{enumitem}
+\usepackage{graphicx}
+\usepackage{hyperref}
+\usepackage{qrcode}
+\usepackage{pgf-umlsd}
+\usepackage{tikz}
+\usetikzlibrary{shapes,arrows}
+\usetikzlibrary{positioning}
+\usetikzlibrary{calc}
+\usetikzlibrary{quotes}
+\author{Christian Grothoff}
+\title{Flows in the GNU Taler System}
+
+\begin{document}
+
+\tableofcontents
+
+\newcommand\TALER{TALER OPERATIONS AG}
+\newcommand\CURRENCY{CHF}
+\newcommand\LAND{der Schweiz}
+
+\section{Transaktionen im Taler-Bezahlsystem}\label{sec:Transaktionen}
+
+Dieser Abschnitt stellt die Transaktionen im Taler-Bezahlsystem
+vor. Die Grafiken geben wieder, in welcher Reihenfolge die beteiligten
+Parteien interagieren. \\
+F\"ur jede einzelne Transaktion ist die automatische Ausl\"osung von
+Compliance-Prozessen durch den Taler-Exchange einstellbar.
+Die im Rahmen des jeweiligen Compliance-Prozesses erzwungenen
+Pr\"ufschritte beschreibt Abschnitt~\ref{sec:triggers}.
+
+Folgende Transaktionen kommen als Ausl\"oser f\"ur AML- und KYC-Prozesse
+in Betracht:
+\begin{description}[noitemsep]
+  \item[withdraw] Ein Nutzer hebt digitales Bargeld (e-money) in Form von
+  Taler-Coins in ein Taler-Wallet ab
+  \item[reimburse] Ein Nutzer l\"asst den Gegenwert von Taler-Coins vom
+  Taler-Exchange an das urspr\"ungliche IBAN-Bankkonto zur\"uck\"uberweisen
+  \item[pay] Ein Nutzer zahlt zugunsten eines IBAN-Bankkontos des Empf\"angers
+  \item[refund] Ein Verk\"aufer erteilt einem Zahlenden die R\"uckerstattung
+  eines Zahlbetrags
+  \item[push] Ein Nutzer sendet einen Zahlbetrag an ein anderes Taler-Wallet
+  \item[pull] Ein Nutzer stellt einem anderen Taler-Wallet eine Rechnung aus
+  und fordert eine Zahlung von diesem Wallet
+  \item[shutdown] Der Betreiber des Taler-Exchange informiert die Inhaber von
+  Coins, die diese von jenem Exchange abgehoben hatten, dass der Exchange
+  geplant eingestellt und die Gegenwerte der Coins restituiert werden
+\end{description}
+
+Die Nutzer beginnen ein gesch\"aftliches Nutzungsverh\"altnis mit
+\TALER{}, wenn sie ihre Taler-Wallets anweisen, eine Abhebung durchzuf\"uhren.
+Das Taler-Bezahlsystem verwendet jedoch keine Konten, sondern wert-basierte
+Token und explizit keine konten-basierten Geld-\"Aquivalente.
+Taler soll digitales Bargeld sein und erlaubt technisch bedingt
+kein Nachvollziehen der Transaktionen seiner Nutzer, wie es Konten mit
+Eing\"angen und Ausg\"angen von Zahlungen erm\"oglichen w\"urden.
+Es gibt daher kein ``Er\"offnen'' oder ``Schliessen'' von Konten der Nutzer.
+Die Begriffe ``opening'' und ``closing'' lassen sich deshalb auch nicht auf
+das System anwenden oder \"ubertragen. \\
+
+Die Nutzer k\"onnen
+\begin{enumerate}[noitemsep]
+\item die treuh\"andisch verwalteten Einlagen gezielt auf ein bestimmtes
+Bankkonto auszahlen lassen,
+%(siehe Abschnitt~\ref{sec:deposit})
+\item an einen Verk\"aufer zahlen,
+%(siehe Abschnitt~\ref{sec:deposit})
+\item einem anderen Empf\"anger mittels peer-to-peer-Verfahren Coins zukommen
+lassen
+%(siehe Abschnitte~\ref{sec:push} und~\ref{sec:pull})
+\item die Coins in ihrem Wallet, das verloren ging oder zerst\"ort wurde,
+durch Ablauf der G\"ultigkeit entwerten lassen (dies w\"are ebenso der Fall
+bei einer langen Zeit ohne Internet-Anbindung oder ohne Installation),
+\item den Wert der Coins im Wallet durch Zahlung von Geb\"uhren f\"ur
+die Verl\"angerung ihrer G\"ultigkeit langsam verringern lassen.
+%(siehe Abschnitt~\ref{sec:fees:coin})
+\end{enumerate}
+
+Das Taler-Bezahlsystem verwehrt den Nutzern kategorisch die Abhebung
+von h\"oheren Betr\"agen als 5.000 \CURRENCY{} pro Monat bzw. von
+mehr als 15.000 \CURRENCY{} pro Jahr. Damit wird gew\"ahrleistet,
+dass die Nutzer stets unterhalb der Grenzwerte bleiben, ab denen die
+meisten Pr\"ufschritte aufgrund regulatorischer Bestimmungen erforderlich
+werden. \TALER{} stellt dar\"uber hinaus sicher, dass die Nutzer
+ausschliesslich in \LAND{} ans\"assig sind
+(siehe Abschnitt~\ref{sec:proc:domestic}), da auf ihrer Seite ein Bankkonto
+in \LAND{} f\"ur die \"Uberweisungen an den Taler-Exchange und/oder
+eine Telefonnummer mit entsprechender Vorwahl (++41) ben\"otigt werden.
+Zus\"atzlich setzt das Taler-Wallet zu jeder Zeit eine Obergrenze
+von 5.000 \CURRENCY{} auf die Coin-Betr\"age in Summe fest, so dass es
+keine weitere Abhebung \"uber diesen Grenzwert hinaus bewirken kann.
+
+F\"ur {\bf Verk\"aufer} beginnt ein gesch\"aftliches Nutzungsverh\"altnis
+mit \TALER{}, sobald sie Geldeing\"ange auf ihren IBAN-Bankkonten erhalten,
+die als Zahlungen von Nutzern des Taler-Bezahlsystems ausgel\"ost wurden
+(siehe Abschnitt~\ref{sec:deposit}). Sollten die Summen der Eing\"ange
+5.000 \CURRENCY{} pro Monat bzw. 15.000 \CURRENCY{} pro Jahr \"ubersteigen,
+kommt es zu einer KYB-Pr\"ufung, die dem Begriff ``Er\"offnen'' eines
+Kontos entspricht und die eine aktualisierte KYB-Information sowie
+die Pr\"ufung von Sanktionslisten erfordert, sofern der Verk\"aufer
+innerhalb von 24 Monaten wenigstens einen Geldeingang erhielt.
+
+Im Gegensatz zu normalen Nutzern k\"onnen Verk\"aufer im Prinzip
+Zahlungen ohne Limit empfangen. Allerdings m\"ussen diese Transaktionen
+auch wirklich als Eing\"ange auf dem Bankkonto des Unternehmens verzeichnet
+werden (im Kontoauszug). In Abh\"angigkeit von den an das Gesch\"aftskonto
+\"uberwiesenen Betr\"agen wird der Verk\"aufer einer KYB-Pr\"ufung unterzogen
+(siehe Abschnitt~\ref{sec:KYB}). Dies gilt ebenso f\"ur
+Geldw\"asche-\"Uberpr\"ufungen (AML checks).
+
+Das Taler-Bezahlsystem transferiert lediglich Gelder auf die bestehenden
+Bankkonten der Verk\"aufer, die f\"ur ihre G\"uterleistungen Zahlungen
+der Nutzer erhalten, f\"ur die bereits bei der \"Uberweisung von deren
+Kundenkonten eine KYC-Pr\"ufung erfolgte. Daher wird unseres Erachtens
+der Betreiber eines Taler-Exchange keine Mittelherkunft verlangen bzw. 
+nachweisen m\"ussen
+\footnote{Wenn Unternehmen das Taler-Bezahlsystem ihrerseits f\"ur 
+Zahlungen nutzen wollen, m\"ussen sie genauso wie alle anderen Nutzer 
+zuerst Geld von ihrem Bankkonto an einen Taler-Exchange \"uberweisen, 
+eine KYC-Pr\"ufung absolvieren und dann ihr Wallet Coins abheben lassen.
+F\"ur die gesch\"aftlichen K\"aufer gelten ebenfalls die Limits wie 
+f\"ur alle anderen Nutzer.}.
+
+
+\include{int-withdraw}
+\include{int-deposit}
+\include{int-pay}
+\include{int-refund}
+\include{int-push}
+\include{int-pull}
+\include{int-shutdown}
+
+
+
+\chapter{Regulatory Triggers} \label{chap:triggers}
+
+In this chapter we show decision diagrams for regulatory processes of the
+various core operations of the GNU Taler payment system.  In each case, the
+{\bf start} state refers to one of the interactions described in the previous
+chapter.  The payment system will then use the process to arrive at an {\bf
+  allow} decision which permits the transaction to go through, or at a {\bf
+  deny} decision which ensures that the funds are not moved.
+
+The specific {\em decisions} (in green) depend on the risk profile and the
+regulatory environment. The tables in each section list the specific values
+that are to be configured.
+
+There are five types if interactions that can trigger regulatory processes:
+
+\begin{description}
+  \item[withdraw] a customer withdraws digital cash from their {\bf bank account}
+  \item[deposit] a merchant's {\bf bank account} is designated to receive a payment in digital cash
+  \item[push] a {\bf wallet} accepts a payment from another wallet
+  \item[pull] a {\bf wallet} requests a payment from another wallet
+  \item[balance] a withdraw or P2P payment causes the balance of a {\bf wallet} to exceed a given threshold
+\end{description}
+
+We note in bold the {\bf anchor} for the regulator process. The anchor is used
+to link the interaction to an identity.  Once an identity has been established
+for a particular anchor, that link is considered established for all types of
+activities involving that anchor.  A wallet is uniquely identified in the
+system by its unique cryptographic key.  A bank account is uniquely identified
+in the system by its (RFC 8905) bank routing data (usually including BIC, IBAN
+and account owner name).
+
+The KYC and AML processes themselves are described in
+Chapter~\ref{chap:regproc}.
+
+\include{kyc-withdraw}
+\include{kyc-deposit}
+\include{kyc-push}
+\include{kyc-pull}
+\include{kyc-balance}
+
+\chapter{Regulatory Processes} \label{chap:regproc}
+
+This chapter describes the interactions between the customer, exchange and
+organizations or staff assisting with regulatory processes designed to ensure
+that customers are residents in the area of operation of the payment service
+provider, are properly identified, and do not engage in money laundering.
+
+The three main regulatory processes are:
+
+\begin{description}
+\item[domestic check] This process establishes that a user is generally
+  eligible to use the payment system.  The process checks that the user has an
+  eligible address, but stops short of establishing the user's identity.
+\item[kyc] This process establishes a user's legal identity, possibly
+  using external providers to review documents and check against blacklists.
+\item[aml] The AML process reviews suspicious payment activities for
+  money laundering. Here AML staff reviews all collected information.
+\end{description}
+
+\include{proc-domestic}
+%\include{proc-kyc}
+\include{proc-kyb}
+\include{proc-aml}
+
+\chapter{Fees} \label{chap:fees}
+
+The business model for operating a Taler exchange is to charge transaction
+fees.  Fees are charged on certain operations by the exchange.  There are two
+types of fees, {\bf wire fees} and {\bf coin fees}.  This chapter describes
+the fee structure.
+
+Fixed, amount-independent {\bf wire fees} are charged on wire transfers using
+the core banking system.  Details on wire fees are described in
+Section~\ref{sec:fees:wire}.
+
+Coin fees are more complex, as they do not exactly follow neither the usual
+percentage of volume model of other payment systems.  Instead, coin fees are
+applied per coin, resulting in a {\em logarithmic} fee structure.  As a
+result, the effective fee {\em percentage} for tiny transactions is high (for
+example 50\% for transactions of 0.0025 CHF) while the effective fee
+percentage for large transactions is nominal (for example $\approx$ 0.05\% for
+transactions of $\approx$ 40 CHF). Details on coin fees are described in
+Section~\ref{sec:fees:coin}.
+
+Fees are configurable (and that fee types beyond those described here are
+supported by the software). Thus, the specific fees may be adjusted in the
+future based on business decisions.  However, changes to the fees are never
+retroactively applied to coins already in circulation.  Wire fees that have
+been publicly announced for a particular time period also cannot be changed.
+Finally, any change to the terms of service must also be explicitly accepted
+by the users before they withdraw additional funds.
+
+
+\include{fees-wire}
+\include{fees-coins}
+%\include{fees-other}
+
+
+\end{document}
diff --git a/src/exchange/taler-exchange-httpd_purses_get.c b/src/exchange/taler-exchange-httpd_purses_get.c
index 613372357..5e4e0619f 100644
--- a/src/exchange/taler-exchange-httpd_purses_get.c
+++ b/src/exchange/taler-exchange-httpd_purses_get.c
@@ -385,7 +385,10 @@ TEH_handler_purses_get (struct TEH_RequestContext *rc,
     if (0 <
         TALER_amount_cmp (&gc->amount,
                           &gc->deposited))
+    {
+      /* amount > deposited: not yet fully paid */
       dt = GNUNET_TIME_UNIT_ZERO_TS;
+    }
     if (TALER_EC_NONE !=
         (ec = TALER_exchange_online_purse_status_sign (
            &TEH_keys_exchange_sign_,
diff --git a/src/testing/testing_api_helpers_auditor.c b/src/testing/testing_api_helpers_auditor.c
deleted file mode 100644
index 2ae1efb25..000000000
--- a/src/testing/testing_api_helpers_auditor.c
+++ /dev/null
@@ -1,232 +0,0 @@
-/*
-  This file is part of TALER
-  Copyright (C) 2018 Taler Systems SA
-
-  TALER is free software; you can redistribute it and/or modify
-  it under the terms of the GNU General Public License as
-  published by the Free Software Foundation; either version 3, or
-  (at your option) any later version.
-
-  TALER is distributed in the hope that it will be useful, but
-  WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
-
-  You should have received a copy of the GNU General Public
-  License along with TALER; see the file COPYING.  If not, see
-  <http://www.gnu.org/licenses/>
-*/
-/**
- * @file testing/testing_api_helpers_auditor.c
- * @brief helper functions
- * @author Christian Grothoff
- */
-#include "platform.h"
-#include "taler_json_lib.h"
-#include <gnunet/gnunet_curl_lib.h>
-#include "taler_testing_lib.h"
-#include "taler_auditor_service.h"
-
-
-/**
- * Closure for #cleanup_auditor.
- */
-struct CleanupContext
-{
-  /**
-   * Where we find the state to clean up.
-   */
-  struct TALER_TESTING_Interpreter *is;
-
-  /**
-   * Next cleanup routine to call, NULL for none.
-   */
-  GNUNET_SCHEDULER_TaskCallback fcb;
-
-  /**
-   * Closure for @e fcb
-   */
-  void *fcb_cls;
-};
-
-
-/**
- * Function to clean up the auditor connection.
- *
- * @param cls a `struct CleanupContext`
- */
-static void
-cleanup_auditor (void *cls)
-{
-  struct CleanupContext *cc = cls;
-  struct TALER_TESTING_Interpreter *is = cc->is;
-
-  TALER_AUDITOR_disconnect (is->auditor);
-  is->auditor = NULL;
-  if (NULL != cc->fcb)
-    cc->fcb (cc->fcb_cls);
-  GNUNET_free (cc);
-}
-
-
-/**
- * Closure for #auditor_main_wrapper()
- */
-struct MainWrapperContext
-{
-  /**
-   * Main function to launch.
-   */
-  TALER_TESTING_Main main_cb;
-
-  /**
-   * Closure for @e main_cb.
-   */
-  void *main_cb_cls;
-
-  /**
-   * Configuration we use.
-   */
-  const struct GNUNET_CONFIGURATION_Handle *cfg;
-
-  /**
-   * Name of the configuration file.
-   */
-  const char *config_filename;
-
-};
-
-
-/**
- * Function called with information about the auditor.
- *
- * @param cls closure
- * @param hr http response details
- * @param vi basic information about the auditor
- * @param compat protocol compatibility information
- */
-static void
-auditor_version_cb (void *cls,
-                    const struct TALER_AUDITOR_HttpResponse *hr,
-                    const struct TALER_AUDITOR_VersionInformation *vi,
-                    enum TALER_AUDITOR_VersionCompatibility compat)
-{
-  struct TALER_TESTING_Interpreter *is = cls;
-
-  (void) hr;
-  (void) vi;
-  if (TALER_AUDITOR_VC_MATCH != compat)
-  {
-    TALER_TESTING_interpreter_fail (is);
-    return;
-  }
-  is->auditor_working = GNUNET_YES;
-}
-
-
-/**
- * Setup the @a is 'auditor' member before running the main test loop.
- *
- * @param cls must be a `struct MainWrapperContext *`
- * @param[in,out] is interpreter state to setup
- */
-static void
-auditor_main_wrapper (void *cls,
-                      struct TALER_TESTING_Interpreter *is)
-{
-  struct MainWrapperContext *mwc = cls;
-  struct CleanupContext *cc;
-  char *auditor_base_url;
-
-  if (GNUNET_OK !=
-      GNUNET_CONFIGURATION_get_value_string (mwc->cfg,
-                                             "auditor",
-                                             "BASE_URL",
-                                             &auditor_base_url))
-  {
-    GNUNET_log_config_missing (GNUNET_ERROR_TYPE_ERROR,
-                               "auditor",
-                               "BASE_URL");
-    return;
-  }
-
-  is->auditor = TALER_AUDITOR_connect (is->ctx,
-                                       auditor_base_url,
-                                       &auditor_version_cb,
-                                       is);
-  GNUNET_free (auditor_base_url);
-
-  if (NULL == is->auditor)
-  {
-    GNUNET_break (0);
-    return;
-  }
-
-  cc = GNUNET_new (struct CleanupContext);
-  cc->is = is;
-  cc->fcb = is->final_cleanup_cb;
-  cc->fcb_cls = is->final_cleanup_cb_cls;
-  is->final_cleanup_cb = cleanup_auditor;
-  is->final_cleanup_cb_cls = cc;
-  mwc->main_cb (mwc->main_cb_cls,
-                is);
-}
-
-
-/**
- * Install signal handlers plus schedules the main wrapper
- * around the "run" method.
- *
- * @param cls our `struct MainWrapperContext`
- * @param cfg configuration we use
- * @return #GNUNET_OK if all is okay, != #GNUNET_OK otherwise.
- *         non-GNUNET_OK codes are #GNUNET_SYSERR most of the
- *         times.
- */
-static int
-setup_with_cfg (void *cls,
-                const struct GNUNET_CONFIGURATION_Handle *cfg)
-{
-  struct MainWrapperContext *mwc = cls;
-  struct TALER_TESTING_SetupContext setup_ctx = {
-    .config_filename = mwc->config_filename,
-    .main_cb = &auditor_main_wrapper,
-    .main_cb_cls = mwc
-  };
-
-  mwc->cfg = cfg;
-  return TALER_TESTING_setup_with_auditor_and_exchange_cfg (&setup_ctx,
-                                                            cfg);
-}
-
-
-/**
- * Install signal handlers plus schedules the main wrapper
- * around the "run" method.
- *
- * @param main_cb the "run" method which contains all the
- *        commands.
- * @param main_cb_cls a closure for "run", typically NULL.
- * @param config_filename configuration filename.
- * @return #GNUNET_OK if all is okay, != #GNUNET_OK otherwise.
- *         non-GNUNET_OK codes are #GNUNET_SYSERR most of the
- *         times.
- */
-int
-TALER_TESTING_auditor_setup (TALER_TESTING_Main main_cb,
-                             void *main_cb_cls,
-                             const char *config_filename)
-{
-  struct MainWrapperContext mwc = {
-    .main_cb = main_cb,
-    .main_cb_cls = main_cb_cls,
-    .config_filename = config_filename
-  };
-
-  return GNUNET_CONFIGURATION_parse_and_run (config_filename,
-                                             &setup_with_cfg,
-                                             &mwc);
-}
-
-
-/* end of testing_auditor_api_helpers.c */