[GNUnet-SVN] [taler-bank] branch master updated: minor edits, some restructuring

[gnunet]

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

grothoff pushed a commit to branch master
in repository bank.

The following commit(s) were added to refs/heads/master by this push:
     new dacd671  minor edits, some restructuring
dacd671 is described below

commit dacd6713820d3aeb9a8219fbabb690510b4b1881
Author: Christian Grothoff <address@hidden>
AuthorDate: Thu Jul 27 17:37:38 2017 +0200

    minor edits, some restructuring
---
 doc/taler-bank.texi             | 76 +++++++++++++++++++++++------------------
 talerbank/app/static/web-common |  2 +-
 2 files changed, 43 insertions(+), 35 deletions(-)

diff --git a/doc/taler-bank.texi b/doc/taler-bank.texi
index b737ea9..0eea349 100644
--- a/doc/taler-bank.texi
+++ b/doc/taler-bank.texi
@@ -87,25 +87,33 @@ regulation (such as GDPR).
 
 @section About this manual
 
-This manual documents how banks can integrate with GNU Taler.  At present, 
only the API between the
-bank's website and the Taler wallet is described.  In the future, this manual 
will also discuss the
-demo bank application and further details for the bank integration.
+This manual documents how the demonstrator bank interoperates with the
+other GNU Taler components.  The demonstrator bank implements a simple
+closed banking system for the purpose of illustrating how GNU Taler
+works in the Taler demo. It could also be used as a starting point for
+a local/regional currency.  Finally, ``real'' banks might use it as a
+reference implementation for a tight integration with the GNU Taler
+wallet.
 
 
 @node Reference
 @chapter Reference
 
 @menu
-* Headers for HTTP 202::                 Headers for the 202 status code and 
their effect on the user agent's operation
+* Bank-Wallet interaction::              Tight integration with the bank for 
withdrawal
 * Bank-Exchange interaction::            Money flux to and from the Exchange
 @end menu
 
address@hidden Headers for HTTP 202
address@hidden Headers for HTTP 202
address@hidden Bank-Wallet interaction
address@hidden Bank-Wallet interaction
+
+
 The HTTP status code @code{202 Accepted} can be used by the bank website
 to trigger operations in the user agent.  The operation is determined
 by the @code{X-Taler-Operation} header.  The following operations are 
understood:
 
address@hidden maybe not use a table but subsections here?
+
 @table @code
 @item create-reserve
 Ask the Taler wallet to create a reserve and call back the bank
@@ -123,7 +131,7 @@ the reserve was created and the user has selected an 
exchange.
 @code{X-Taler-Amount}: The amount that will be transferred to the reserve.
 
 @item
address@hidden: JSON-encoded wire details of the sender, that
address@hidden: JSON-encoded wire account details of the sender, that
 is the user that is currently logged in with the bank and creates the reserve.
 
 @end itemize
@@ -133,8 +141,8 @@ The following header is optional:
 @itemize
 @item
 @code{X-Taler-Suggested-Exchange}:  Exchange that the bank recommends
-the customer to use.  Note that this is a suggestion and can be overwritten
-by the user.
+the customer to use.  Note that this is a suggestion and can be ignored
+by the wallet or changed by the user.
 @end itemize
 
 On successful reserve creation, the wallet will navigate to the callback URL
@@ -155,51 +163,51 @@ exchange when transmitting the funds.
 @end itemize
 
 
-
 @item confirm-reserve
-When triggering this operation, the bank confirms that the user completed the
-required steps to transfer funds to an exchange to establish the reserve
-identified by the @code{X-Taler-Reserve-Pub} header. 
 
-This does not guarantee that the reserve is already created at the exchange 
(since the actual
-money transfer might be executed asynchronously), but it informs that wallet 
that it can start
-polling for the reserve.
+To secure the operation, the (demo) bank then shows a "CAPTCHA page"
+-- a real bank would instead show some PIN entry dialog or similar
+security method -- where the customer can finally prove she their
+identity and thereby confirm the withdraw operation to the bank.
+
+Afterwards, the bank needs to confirm to the wallet that the user
+completed the required steps to transfer funds to an exchange to
+establish the reserve identified by the @code{X-Taler-Reserve-Pub}
+header.
+
+This does not guarantee that the reserve is already created at the
+exchange (since the actual money transfer might be executed
+asynchronously), but it informs that wallet that it can start polling
+for the reserve.
 
 @end table
 
+
 @node Bank-Exchange interaction
 @section Bank-Exchange interaction
+
 The interaction between a bank and the exchange happens in two situations:
-when a wallet withdraws coins and when the exchange pays a merchant.
+when a wallet withdraws coins, and when the exchange pays a merchant.
 
 @subsection Withdraw
-In the context of the @code{create-reserve} command, upon confirming the
-exchange, the wallet visits the @code{X-Taler-Callback-Url}, including the
-following arguments in the URL: @code{amount}, @code{exchange_url},
address@hidden, @code{exchange_account_number}, @code{sender_wiredetails}.
-
-To secure the operation, the bank then shows a "CAPTCHA page" -- any bank
-is free to choose its own security method -- where the customer can finally
-prove she is not a bot and finally confirm the withdraw operation.
 
-Upon confirmation, the bank will firstly wire transfer the withdrawn amount
-from the customer account to the exchange's.  After this operation is done,
-the exchange needs to be informed so that it will create the reserve.
+Once a withdrawal operation with the wallet has been confirmed, the
+the bank must wire transfer the withdrawn amount from the customer
+account to the exchange's.  After this operation is done, the exchange
+needs to be informed so that it will create the reserve.
 
-To this purpose, the bank will use the exchange's @code{/admin/add/incoming}
+For the moment, the bank will use the exchange's @code{/admin/add/incoming}
 API, providing those arguments it got along the @code{X-Taler-Callback-Url} 
URL.
+(In the future, the exchange will poll for this information.)
 However, the bank will define two additional values for this API: 
@code{execution_date}
 (a operation's timestamp), and @code{transfer_details} (just a "seed" to make 
unique the
 operation).  See 
@url{https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions}.
 
-The HTTP status code returned to the user agent is whatever status code
-the exchange gives back for the call to @code{/admin/add/incoming}.  However,
-it's bank's responsibility to let the user know about the outcome.
 
 @subsection Exchange pays merchant
 
-To provide this service, the bank exposes the @code{/admin/add/incoming}
-API to exchanges.
+To allow the exchange to send payments to a merchant, the bank exposes
+the @code{/admin/add/incoming} API to exchanges.
 
 @table @code
 
diff --git a/talerbank/app/static/web-common b/talerbank/app/static/web-common
index 489a9e3..d7e0135 160000
--- a/talerbank/app/static/web-common
+++ b/talerbank/app/static/web-common
@@ -1 +1 @@
-Subproject commit 489a9e38e6960fdce309ab8cf5ff66d930ecb3bc
+Subproject commit d7e013594d15388b1a7342a44a0e9c8d4ecca82d

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