[taler-cashless2ecash] branch master updated: spec: fix api spec and convert to rst format

[gnunet]

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

joel-haeberli pushed a commit to branch master
in repository cashless2ecash.

The following commit(s) were added to refs/heads/master by this push:
     new ca86b66  spec: fix api spec and convert to rst format
ca86b66 is described below

commit ca86b665f7b52a55800fb9389ffc8d3afa5322fd
Author: Joel-Haeberli <haebu@rubigen.ch>
AuthorDate: Wed Mar 6 11:14:41 2024 +0100

    spec: fix api spec and convert to rst format
---
 docs/content/appendix/meeting_notes.tex |   7 +-
 docs/thesis.pdf                         | Bin 1076156 -> 1292636 bytes
 specs/api-nonce2ecash.rst               | 120 ++++++++++++++++++++++++++++++++
 3 files changed, 125 insertions(+), 2 deletions(-)

diff --git a/docs/content/appendix/meeting_notes.tex 
b/docs/content/appendix/meeting_notes.tex
index dcb9ce6..d8081be 100644
--- a/docs/content/appendix/meeting_notes.tex
+++ b/docs/content/appendix/meeting_notes.tex
@@ -120,7 +120,8 @@
 
 \textbf{Topics}
 \begin{itemize}
-    \item API Spec
+    \item API Spec nonce2ecash
+    \item Database Spec nonce2ecash
 \end{itemize}
 
 \textbf{Questions}
@@ -132,7 +133,9 @@
 
 \textbf{Action points}
 \begin{itemize}
-    \item
+    \item write API specification in .rst format (see /docs/core/api-*.rst in 
taler docs git)
+    \item use Bank integration API
+    \item write SQL schema and generate UML using schema-spy instead of 
writing UML.
 \end{itemize}
 
 \textbf{Decisions}
diff --git a/docs/thesis.pdf b/docs/thesis.pdf
index 58d657e..78e3a00 100644
Binary files a/docs/thesis.pdf and b/docs/thesis.pdf differ
diff --git a/specs/api-nonce2ecash.rst b/specs/api-nonce2ecash.rst
new file mode 100644
index 0000000..47c6e46
--- /dev/null
+++ b/specs/api-nonce2ecash.rst
@@ -0,0 +1,120 @@
+..
+  This file is part of GNU TALER.
+
+  Copyright (C) 2014-2023 Taler Systems SA
+
+  TALER is free software; you can redistribute it and/or modify it under the
+  terms of the GNU Affero General Public License as published by the Free 
Software
+  Foundation; either version 2.1, 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 Affero General Public License for more 
details.
+
+  You should have received a copy of the GNU Affero General Public License 
along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+
+  @author Joel Häberli
+
+==========================
+Taler nonce2ecash API
+==========================
+
+This chapter describe the APIs that third party providers need to integrate 
withdrawal through indirect
+payment channels like credit cards or ATM.
+
+.. contents:: Table of Contents
+
+----------------------------
+Configuration of nonce2ecash
+----------------------------
+
+.. http:get:: /config
+
+  Return the protocol version and configuration information about the 
nonce2ecash API.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The exchange responds with a `IntegrationConfig` object. This request 
should
+    virtually always be successful.
+
+  **Details:**
+
+  .. ts:def:: Nonce2ecashConfig
+
+    interface Nonce2ecashConfig {
+      // Name of the API.
+      name: "taler-nonce2ecash";
+
+      // libtool-style representation of the nonce2ecash protocol version, see
+      // 
https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
+      // The format is "current:revision:age".
+      version: string;
+    }
+
+
+-----------------------------
+Withdrawing using nonce2ecash
+-----------------------------
+
+Withdrawals with a nonce2ecash are based on withdrawal operations which 
register a withdrawal identifier
+(nonce) at the nonce2ecash component. The provider must first create a unique 
identifier for the withdrawal 
+operation (the ``WITHDRAWAL_ID``) to interact with the withdrawal operation 
and eventually withdraw using the wallet.
+
+.. http:post:: /withdrawal-operation
+
+  Query information about a withdrawal operation, identified by the 
``WITHDRAWAL_ID``.
+
+  **Request:**
+
+  .. ts:def:: WithdrawRegistration
+
+    interface WithdrawRegistration {
+      // Maps a nonce generated by the provider to a reserve public key 
generated by the wallet.
+      withdrawal_id: ShortHashCode;
+
+      // Reserve public key generated by the wallet.
+      // According to TALER_ReservePublicKeyP 
(https://docs.taler.net/core/api-common.html#cryptographic-primitives)
+      reserve_pub_key: EddsaPublicKey;
+
+      // Optional amount for the withdrawal.
+      amount?: Amount;
+
+      // Id of the provider requesting a withdrawal by nonce.
+      providerId: SafeUint64;
+    }
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The withdrawal was successfully registered
+
+.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
+
+    Notifies nonce2ecash about an executed payment for a specific withdrawal.
+
+  **Request:**
+
+  .. ts:def:: PaymentNotification
+
+    interface PaymentNotification {
+
+      // Unique identifier of the provider transaction.
+      provider_transaction_id: string;
+
+      // Specifies the amount which was payed to the provider (without fees).
+      // This amount shall be put into the reserve linked to by the withdrawal 
id. 
+      amount: Amount;
+
+      // Fees associated with the payment.
+      fees: Amount;
+    }
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    nonce2ecash received the ``PaymentNotification`` successfully and will 
further process
+    the withdrawal.
+  :http:statuscode:`404 Not found`:
+    nonce2ecash does not have a withdrawal registered with the specified 
``WITHDRAWAL_ID``.

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.