[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: thoughts for C2EC discussion tomorro
|
From: |
gnunet |
|
Subject: |
[taler-docs] branch master updated: thoughts for C2EC discussion tomorrow |
|
Date: |
Tue, 23 Apr 2024 19:23:12 +0200 |
This is an automated email from the git hooks/post-receive script.
grothoff pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new edf57eef thoughts for C2EC discussion tomorrow
edf57eef is described below
commit edf57eef91cb1ef1830dd90beda70357b18e9848
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue Apr 23 19:23:07 2024 +0200
thoughts for C2EC discussion tomorrow
---
core/api-bank-integration.rst | 151 ++++++++++++++++++++++++++++++------------
core/api-corebank.rst | 36 +++++++---
2 files changed, 132 insertions(+), 55 deletions(-)
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
index ed4d8de0..1d0f9db9 100644
--- a/core/api-bank-integration.rst
+++ b/core/api-bank-integration.rst
@@ -1,7 +1,7 @@
..
This file is part of GNU TALER.
- Copyright (C) 2014-2023 Taler Systems SA
+ Copyright (C) 2014-2024 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
@@ -29,7 +29,7 @@ to tightly integrate with GNU Taler.
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **2**.
+ This specification corresponds to ``current`` protocol being **v2**.
**Response:**
@@ -91,36 +91,52 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to
interact with the withdr
The withdrawal operation is known to the bank, and details are given
in the `BankWithdrawalOperationStatus` response body.
:http:statuscode:`404 Not found`:
- The operation was not found
+ The operation was not found.
**Details:**
.. ts:def:: BankWithdrawalOperationStatus
- export class BankWithdrawalOperationStatus {
+ interface BankWithdrawalOperationStatus {
// Current status of the operation
// pending: the operation is pending parameters selection (exchange and
reserve public key)
// selected: the operations has been selected and is pending confirmation
// aborted: the operation has been aborted
// confirmed: the transfer has been confirmed and registered by the bank
- // @since v1
+ // @since **v1**
status: "pending" | "selected" | "aborted" | "confirmed";
// Amount that will be withdrawn with this operation
- // (raw amount without fee considerations).
- amount: Amount;
-
- // Bank account of the customer that is withdrawing, as a
- // ``payto`` URI.
+ // (raw amount without fee considerations). Only
+ // given once the amount is fixed and cannot be changed.
+ // Optional since **vC2EC**.
+ amount?: Amount;
+
+ // Suggestion for the amount to be withdrawn with this
+ // operation. Given if a suggestion was made but the
+ // user may still change the amount.
+ // Optional since **vC2EC**.
+ suggested_amount?: Amount;
+
+ // Bank account of the customer that is debiting, as an
+ // RFC 8905 ``payto`` URI.
sender_wire?: string;
- // Suggestion for an exchange given by the bank.
+ // Base URL of the suggested exchange. The bank may have
+ // neither a suggestion nor a requirement for the exchange.
+ // This value is typically set in the bank's configuration.
suggested_exchange?: string;
+ // Base URL of an exchange that must be used. Optional,
+ // not given *unless* a particular exchange is mandatory.
+ // This value is typically set in the bank's configuration.
+ // @since **vC2EC**
+ required_exchange?: string;
+
// URL that the user needs to navigate to in order to
// complete some final confirmation (e.g. 2FA).
// Only applicable when ``status`` is ``selected`` or ``pending``.
- // It may contain withdrawal operation id
+ // It may contain the withdrawal operation id.
confirm_transfer_url?: string;
// Wire transfer types supported by the bank.
@@ -128,25 +144,25 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to
interact with the withdr
// Reserve public key selected by the exchange,
// only non-null if ``status`` is ``selected`` or ``confirmed``.
- // @since v1
+ // @since **v1**
selected_reserve_pub?: EddsaPublicKey;
- // Exchange account selected by the wallet
+ // Exchange account selected by the wallet;
// only non-null if ``status`` is ``selected`` or ``confirmed``.
- // @since v1
+ // @since **v1**
selected_exchange_account?: string;
- // @deprecated since v1, use ``status`` instead
+ // @deprecated since **v1**, use ``status`` instead
// Indicates whether the withdrawal was aborted.
aborted: boolean;
- // @deprecated since v1, use ``status`` instead
+ // @deprecated since **v1**, use ``status`` instead
// Has the wallet selected parameters for the withdrawal operation
// (exchange and reserve public key) and successfully sent it
// to the bank?
selection_done: boolean;
- // @deprecated since v1, use ``status`` instead
+ // @deprecated since **v1**, use ``status`` instead
// The transfer has been confirmed and registered by the bank.
// Does not guarantee that the funds have arrived at the exchange
already.
transfer_done: boolean;
@@ -155,16 +171,27 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to
interact with the withdr
.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
+ This endpoint is used by the GNU Taler wallet to supply additional
+ details needed to complete a withdraw operation.
+
**Request:**
.. ts:def:: BankWithdrawalOperationPostRequest
interface BankWithdrawalOperationPostRequest {
- // Reserve public key.
+
+ // Reserve public key that should become the wire transfer
+ // subject to fund the withdrawal.
reserve_pub: EddsaPublicKey;
- // Payto address of the exchange selected for the withdrawal.
- selected_exchange?: string;
+ // RFC 8905 (payto) address of the exchange account to be
+ // credited for the withdrawal.
+ selected_exchange: string;
+
+ // Selected amount to be transferred. Optional if the
+ // backend already knows the amount.
+ // @since **vC2EC**
+ amount?: Amount;
}
**Response:**
@@ -175,11 +202,15 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to
interact with the withdr
:http:statuscode:`404 Not found`:
The bank does not know about a withdrawal operation with the specified
``WITHDRAWAL_ID``.
:http:statuscode:`409 Conflict`:
- * ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT`` :
+ * ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT``:
The wallet selected a different exchange or reserve public key under the
same withdrawal ID.
- * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT`` : the reserve public key
is already used.
- * ``TALER_EC_BANK_UNKNOWN_ACCOUNT`` : the selected exchange account was
not found.
- * ``TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE`` : the selected account is not
an exchange.
+ * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the reserve public key
is already used.
+ * ``TALER_EC_BANK_UNKNOWN_ACCOUNT``: the selected exchange account was not
found.
+ * ``TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE``: the selected account is not
an exchange.
+ * ``TALER_EC_BANK_AMOUNT_DIFFERS`` : the specified amount will not work
for this
+ withdrawal (since **vC2EC**).
+ * ``TALER_EC_BANK_AMOUNT_REQUIRED`` : the backend requires an amount to be
+ specified (since **vC2EC**).
**Details:**
@@ -199,6 +230,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to
interact with the withdr
// Only applicable when ``status`` is ``selected`` or ``pending``.
// It may contain withdrawal operation id
confirm_transfer_url?: string;
+
// The transfer has been confirmed and registered by the bank.
// Does not guarantee that the funds have arrived at the exchange
already.
transfer_done: boolean;
@@ -206,21 +238,49 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to
interact with the withdr
.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/confirm
- Since protocol vC2EC
+ Endpoint for providers to notify the bank about a payment having happened.
+ This will cause the bank to validate the transaction and allow the
+ withdrawal to proceed. The API is idempotent, meaning sending a payment
+ notification for the same ``WITHDRAWAL_ID`` return successfuly but not
+ change anything. This endpoint is always *optional*, the bank, exchange and
+ wallet should all eventually notice the wire transfer with or without this
+ endpoint being called. However, by calling this endpoint checks that might
+ otherwise only happen periodically can be triggered immediately.
+
+ .. note::
+
+ A bank shall **never** just accept this claim that the payment was
+ confirmed, but instead needs to internally attest that the payment was
+ successful using provider-specific transaction validation logic! The point
+ of this endpoint is merely to trigger this validation **now**.
- Allows a provider to notify the Bank about the payment. This will trigger a
payment
- attestation at the provider, which eventually confirms the payment and
allows the
- withdrawal. The API is idempotent, meaning sending a payment
- notification for the same ``WITHDRAWAL_ID`` return successfuly but not
change anything.
+ Since protocol **vC2EC**.
- Attention: A bank shall **never** just accept the payment directly but
instead attest
- the payment using provider specific attestation logic!
+ FIXME: If this is *just* a trigger, what is the point in supplying the body?
+ After all, a wallet could just do the same POST and then we'd store/process
+ completely bogus information!
+
+ FIXME: why not use /accounts/$USERNAME/withdrawals/$WITHDRAWAL_ID/confirm?
**Request:**
+ The body of the request must be a `BankWithdrawalConfirmationRequest`.
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The payment notification was processed successfully.
+ :http:statuscode:`404 Not found`:
+ The withdrawal operation was not found.
+ :http:statuscode:`409 Conflict`:
+ The withdrawal operation has been aborted previously and can't be aborted
+
+ **Details:**
+
.. ts:def:: BankWithdrawalConfirmationRequest
interface WithdrawalConfirmationRequest {
+
// The provider specific transaction identifier.
// This identifier is used by the bank to attest the
// payment at the providers backend.
@@ -234,6 +294,8 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to
interact with the withdr
// This will decide about how the withdrawal
// is attested. The device must be known to
// the exchange and be somehow registered.
+ //
+ // FIXME: probably more general to use a *string*.
terminal_id: number;
// The amount to withdraw. Fees are to be sent in the
@@ -244,21 +306,21 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to
interact with the withdr
card_fees: Amount;
}
- **Response**
-
- :http:statuscode:`204 No content`:
- The payment notification was processed successfully.
- :http:statuscode:`404 Not found`:
- The withdrawal operation was not found.
- :http:statuscode:`409 Conflict`:
- The withdrawal operation has been aborted previously and can't be aborted
-
.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort
Aborts ``WITHDRAWAL_ID`` operation. Has no effect on an already aborted
- operation.
- Since protocol v2.
+ operation. This endpoint can be used by the wallet if the user aborts
+ the transaction, ensuring that the operation is also aborted at the
+ bank.
+
+ **FIXME**: Should we not change this to be a **delete**?
+
+ Since protocol **v2**.
+
+ **Request:**
+
+ The request body is empty.
**Response:**
@@ -267,4 +329,5 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to
interact with the withdr
:http:statuscode:`404 Not found`:
The withdrawal operation was not found.
:http:statuscode:`409 Conflict`:
- The withdrawal operation has been confirmed previously and can't be
aborted.
+ The withdrawal operation has been confirmed previously and
+ can't be aborted.
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
index 680b2724..878542d3 100644
--- a/core/api-corebank.rst
+++ b/core/api-corebank.rst
@@ -88,7 +88,7 @@ Config
// @since v4, will become mandatory in the next version.
bank_name?: string;
- // Advertised base URL to use when you sharing an URL with another
+ // Advertised base URL to use when you sharing an URL with another
// program.
// @since v4.
base_url?: string;
@@ -472,7 +472,7 @@ Account Management
// Current status of the account
// active: the account can be used
- // deleted: the account has been deleted but is retained for compliance
+ // deleted: the account has been deleted but is retained for compliance
// reasons, only the administrator can access it
// Default to 'active' is missing
// @since v4, will become mandatory in the next version.
@@ -539,7 +539,7 @@ Account Management
// Current status of the account
// active: the account can be used
- // deleted: the account has been deleted but is retained for compliance
+ // deleted: the account has been deleted but is retained for compliance
// reasons, only the administrator can access it
// Default to 'active' is missing
// @since v4, will become mandatory in the next version.
@@ -682,8 +682,8 @@ Transactions
row_id: Integer;
}
-Taler Withdrawals
------------------
+Account withdrawals
+-------------------
.. http:post:: /accounts/$USERNAME/withdrawals
@@ -691,12 +691,7 @@ Taler Withdrawals
**Request:**
- .. ts:def:: BankAccountCreateWithdrawalRequest
-
- interface BankAccountCreateWithdrawalRequest {
- // Amount to withdraw.
- amount: Amount;
- }
+ The request must be a `BankAccountCreateWithdrawalRequest`.
**Response:**
@@ -709,6 +704,25 @@ Taler Withdrawals
**Details:**
+ .. ts:def:: BankAccountCreateWithdrawalRequest
+
+ interface BankAccountCreateWithdrawalRequest {
+
+ // Amount to withdraw.
+ // FIXME: **vC2EC**: make this optional?
+ // FIXME: **vC2EC**: allow making merely a suggestion?
+ amount: Amount;
+
+ // KYC data in case where enable somebody else
+ // to withdraw from "our" account?
+ // FIXME: what would be a good ID?
+ // FIXME: need a way to determine
+ // and return limits per ID!
+ // @since **vC2EC**?
+ kyc_link?: TBD;
+
+ }
+
.. ts:def:: BankAccountCreateWithdrawalResponse
interface BankAccountCreateWithdrawalResponse {
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [taler-docs] branch master updated: thoughts for C2EC discussion tomorrow,
gnunet <=