[taler-docs] branch master updated: terms

[gnunet]

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 81a6e3eb terms
81a6e3eb is described below

commit 81a6e3eb9c7682863183f6f24885508dd042577e
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue Sep 26 14:44:53 2023 +0200

    terms
---
 core/api-donau.rst    | 141 ++++++++++++++++++++------------------------------
 core/api-exchange.rst |   5 +-
 2 files changed, 61 insertions(+), 85 deletions(-)

diff --git a/core/api-donau.rst b/core/api-donau.rst
index 23952a7a..aa1924a2 100644
--- a/core/api-donau.rst
+++ b/core/api-donau.rst
@@ -38,11 +38,9 @@ This API is used by wallets and merchants to obtain global 
information about
 the Donau, such as online signing keys, available donation units and the fee
 structure.  This is typically the first call any Donau client makes, as it
 returns information required to process all of the other interactions with the
-Donau.  The returned information is secured by (1) signature(s) from the Donau,
-especially the long-term offline signing key of the Donau, which clients should
-cache; (2) signature(s) from auditors, and the auditor keys should be
-hard-coded into the wallet as they are the trust anchors for Taler; (3)
-possibly by using HTTPS.
+Donau.  The returned information is secured by signature(s) from the Donau,
+especially the long-term offline signing key of the Donau, which clients
+should cache.
 
 
 .. http:get:: /seed
@@ -57,10 +55,8 @@ possibly by using HTTPS.
 
 .. http:get:: /config
 
-  Return the protocol version and currency supported by this Donau backend, as
-  well as the list of possible KYC requirements.  This endpoint is largely for
-  the SPA for AML officers. Merchants should use ``/keys`` which also contains
-  the protocol version and currency.
+  Return the protocol version, financial domain and currency supported by this
+  Donau backend.
 
   **Response:**
 
@@ -88,14 +84,14 @@ possibly by using HTTPS.
 
 .. http:get:: /keys
 
-  Get a list of all denomination keys offered by the Donau,
+  Get a list of all donation units keys offered by the Donau,
   as well as the Donau's current online signing key.
 
   **Request:**
 
   :query last_issue_date: Optional argument specifying the maximum value of
                           any of the ``stamp_start`` members of the
-                          denomination keys of a ``/keys`` response that is
+                          donation unit keys of a ``/keys`` response that is
                           already known to the client. Allows the Donau to
                           only return keys that have changed since that
                           timestamp.  The given value must be an unsigned
@@ -141,7 +137,7 @@ possibly by using HTTPS.
       master_public_key: EddsaPublicKey;
 
       // Donation Units offered by this donau
-      donaton_units: DonationUnitGroup[];
+      donation_units: DonationUnitGroup[];
 
       // The date when the denomination keys were last updated.
       list_issue_date: Timestamp;
@@ -191,7 +187,7 @@ possibly by using HTTPS.
 
     // Common attributes for all denomination groups
     interface DonauDonationUnitGroupCommon {
-      // How much are coins of this denomination worth?
+      // How much are receipts of this denomination worth?
       value: Amount;
 
     }
@@ -205,21 +201,18 @@ possibly by using HTTPS.
       // When does the denomination key become valid?
       stamp_start: Timestamp;
 
-      // When is it no longer possible to deposit coins
+      // When is it no longer possible to deposit receipts
       // of this denomination?
       stamp_expire_withdraw: Timestamp;
 
-      // Timestamp indicating by when legal disputes relating to these coins 
must
+      // Timestamp indicating by when legal disputes relating to these 
receipts must
       // be settled, as the Donau will afterwards destroy its evidence 
relating to
-      // transactions involving this coin.
+      // transactions involving this receipt.
       stamp_expire_legal: Timestamp;
 
-      // Set to 'true' if the Donau somehow "lost"
-      // the private key. The denomination was not
-      // necessarily revoked, but still cannot be used
-      // to withdraw coins at this time (theoretically,
-      // the private key could be recovered in the
-      // future; coins signed with the private key
+      // Set to 'true' if the Donau somehow "lost" the private key. The 
donation unit was not
+      // revoked, but still cannot be used to withdraw receipts at this time 
(theoretically,
+      // the private key could be recovered in the future; receipts signed 
with the private key
       // remain valid).
       lost?: boolean;
     }
@@ -233,13 +226,13 @@ possibly by using HTTPS.
       // When does the denomination key become valid?
       stamp_start: Timestamp;
 
-      // When is it no longer possible to deposit coins
+      // When is it no longer possible to deposit receipts
       // of this denomination?
       stamp_expire_withdraw: Timestamp;
 
-      // Timestamp indicating by when legal disputes relating to these coins 
must
+      // Timestamp indicating by when legal disputes relating to these 
receipts must
       // be settled, as the donau will afterwards destroy its evidence 
relating to
-      // transactions involving this coin.
+      // transactions involving this receipt.
       stamp_expire_legal: Timestamp;
 
       // Public key for the denomination.
@@ -274,12 +267,6 @@ possibly by using HTTPS.
 
     }
 
-  Fees for any of the operations can be zero, but the fields must still be
-  present. The currency of the ``fee_deposit``, ``fee_refresh`` and 
``fee_refund`` must match the
-  currency of the ``value``.  Theoretically, the ``fee_withdraw`` could be in a
-  different currency, but this is not currently supported by the
-  implementation.
-
   A signing key in the ``signkeys`` list is a JSON object with the following 
fields:
 
   .. ts:def:: SignKey
@@ -360,40 +347,28 @@ Management operations authorized by master key
       // Name in the configuration file that defines this denomination.
       section_name: string;
 
-      // How much are coins of this denomination worth?
+      // How much are receipts of this denomination worth?
       value: Amount;
 
       // When does the denomination key become valid?
       stamp_start: Timestamp;
 
-      // When is it no longer possible to withdraw coins
+      // When is it no longer possible to withdraw receipts
       // of this denomination?
       stamp_expire_withdraw: Timestamp;
 
-      // When is it no longer possible to deposit coins
+      // When is it no longer possible to deposit receipts
       // of this denomination?
       stamp_expire_deposit: Timestamp;
 
-      // Timestamp indicating by when legal disputes relating to these coins 
must
+      // Timestamp indicating by when legal disputes relating to these 
receipts must
       // be settled, as the donau will afterwards destroy its evidence 
relating to
-      // transactions involving this coin.
+      // transactions involving this receipt.
       stamp_expire_legal: Timestamp;
 
       // Public (RSA) key for the denomination.
       denom_pub: RsaPublicKey;
 
-      // Fee charged by the donau for withdrawing a coin of this denomination.
-      fee_withdraw: Amount;
-
-      // Fee charged by the donau for depositing a coin of this denomination.
-      fee_deposit: Amount;
-
-      // Fee charged by the donau for refreshing a coin of this denomination.
-      fee_refresh: Amount;
-
-      // Fee charged by the donau for refunding a coin of this denomination.
-      fee_refund: Amount;
-
       // Signature by the denomination security module
       // over `TALER_DonationUnitKeyAnnouncementPS`
       // for this denomination with purpose
@@ -488,12 +463,12 @@ Management operations authorized by master key
 Withdrawal
 ----------
 
-This API is used by the wallet to obtain digital coins.
+This API is used by the wallet to obtain digital receipts.
 
 When transferring money to the donau such as via SEPA transfers, the donau 
creates
 a *charity*, which keeps the money from the customer.  The customer must
 specify an EdDSA charity public key as part of the transfer, and can then
-withdraw digital coins using the corresponding private key.  All incoming and
+withdraw digital receipts using the corresponding private key.  All incoming 
and
 outgoing transactions are recorded under the corresponding public key by the
 donau.
 
@@ -601,19 +576,17 @@ donau.
       // Amount withdrawn.
       amount: Amount;
 
-      // Hash of the denomination public key of the coin.
+      // Hash of the denomination public key of the receipt.
       h_denom_pub: HashCode;
 
-      // Hash of the blinded coin to be signed.
-      h_coin_envelope: HashCode;
+      // Hash of the blinded receipt to be signed.
+      h_receipt_envelope: HashCode;
 
       // Signature over a `TALER_WithdrawRequestPS`
       // with purpose ``TALER_SIGNATURE_WALLET_CHARITY_WITHDRAW``
       // created with the charity's private key.
       charity_sig: EddsaSignature;
 
-      // Fee that is charged for withdraw.
-      withdraw_fee: Amount;
      }
 
   .. ts:def:: CharityCreditTransaction
@@ -717,8 +690,8 @@ Batch Withdraw
 
 .. http:post:: /charitys/$CHARITY_PUB/batch-withdraw
 
-  Withdraw multiple coins from the same charity.  Note that the client should
-  commit all of the request details, including the private key of the coins and
+  Withdraw multiple receipts from the same charity.  Note that the client 
should
+  commit all of the request details, including the private key of the receipts 
and
   the blinding factors, to disk *before* issuing this request, so that it can
   recover the information if necessary in case of transient failures, like
   power outage, network outage, etc.
@@ -731,7 +704,7 @@ Batch Withdraw
     The request was successful, and the response is a `BatchWithdrawResponse`.
     Note that repeating exactly the same request will again yield the same
     response, so if the network goes down during the transaction or before the
-    client can commit the coin signature to disk, the coin is not lost.
+    client can commit the receipt signature to disk, the receipt is not lost.
   :http:statuscode:`403 Forbidden`:
     A signature is invalid.
     This response comes with a standard `ErrorDetail` response.
@@ -744,9 +717,9 @@ Batch Withdraw
     instead simply wait for up to a day, as the wire transaction might simply
     not yet have completed and might be known to the donau in the near future.
     In this case, the wallet should repeat the exact same request later again
-    using exactly the same blinded coin.
+    using exactly the same blinded receipt.
   :http:statuscode:`409 Conflict`:
-    The balance of the charity is not sufficient to withdraw the coins of the
+    The balance of the charity is not sufficient to withdraw the receipts of 
the
     indicated donation units.  
   :http:statuscode:`410 Gone`:
     A requested denomination key is not yet or no longer valid.
@@ -760,7 +733,7 @@ Batch Withdraw
   .. ts:def:: BatchWithdrawRequest
 
     interface BatchWithdrawRequest {
-      // Array of requests for the individual coins to withdraw.
+      // Array of requests for the individual receipts to withdraw.
       planchets: WithdrawRequest[];
 
     }
@@ -782,10 +755,10 @@ Deposit operations are requested f.e. by a merchant 
during a transaction or a
 bidder during an auction.
 
 For the deposit operation during purchase, the merchant has to obtain the
-deposit permission for a coin from their customer who owns the coin.  When
-depositing a coin, the merchant is credited an amount specified in the deposit
-permission, possibly a fraction of the total coin's value, minus the deposit
-fee as specified by the coin's denomination.
+deposit permission for a receipt from their customer who owns the receipt.  
When
+depositing a receipt, the merchant is credited an amount specified in the 
deposit
+permission, possibly a fraction of the total receipt's value, minus the deposit
+fee as specified by the receipt's denomination.
 
 For auctions, a bidder performs an deposit operation and provides all relevant
 information for the auction policy (such as timeout and public key as bidder)
@@ -797,9 +770,9 @@ proof to the seller for the escrow of sufficient fund.
 
 .. http:POST:: /batch-deposit
 
-  Deposit multiple coins and ask the donau to transfer the given :ref:`amount`
+  Deposit multiple receipts and ask the donau to transfer the given 
:ref:`amount`
   into the merchant's bank account.  This API is used by the merchant to redeem
-  the digital coins.
+  the digital receipts.
 
   **Request:**
 
@@ -819,18 +792,18 @@ proof to the seller for the escrow of sufficient fund.
     If a denomination key is unknown, the response will be
     a `DonationUnitUnknownMessage`.
   :http:statuscode:`409 Conflict`:
-    The deposit operation has either failed because a coin has insufficient
-    residual value, or because the same public key of a coin has been
+    The deposit operation has either failed because a receipt has insufficient
+    residual value, or because the same public key of a receipt has been
     previously used with a different denomination.
     Which case it is
     can be decided by looking at the error code
-    (``TALER_EC_DONAU_DEPOSIT_CONFLICTING_CONTRACT`` (same coin used in 
different ways),
+    (``TALER_EC_DONAU_DEPOSIT_CONFLICTING_CONTRACT`` (same receipt used in 
different ways),
     ``TALER_EC_DONAU_GENERIC_INSUFFICIENT_FUNDS`` (balance insufficient) or
-    ``TALER_EC_DONAU_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``
-    (same coin public key, but different denomination)).
+    ``TALER_EC_DONAU_GENERIC_RECEIPT_CONFLICTING_DENOMINATION_KEY``
+    (same receipt public key, but different denomination)).
     The fields of the response are still evolving (see bug 7267),
     for now the format of the response is a `DepositDoubleSpendError`.
-    The request should not be repeated again with this coin.
+    The request should not be repeated again with this receipt.
   :http:statuscode:`410 Gone`:
     The requested denomination key is not yet or no longer valid.
     It either before the validity start, past the expiration or was revoked. 
The response is a
@@ -844,8 +817,8 @@ proof to the seller for the escrow of sufficient fund.
 
     interface BatchDepositRequest {
 
-      // The list of coins that are going to be deposited with this Request.
-      coins: BatchDepositRequestCoin[];
+      // The list of receipts that are going to be deposited with this Request.
+      receipts: BatchDepositRequestReceipt[];
 
       // FIXME: maybe add tax year?
       
@@ -853,24 +826,24 @@ proof to the seller for the escrow of sufficient fund.
       h_donor: DonorTaxDataHash;
     }
 
-  .. ts:def:: BatchDepositRequestCoin
+  .. ts:def:: BatchDepositRequestReceipt
 
-    interface BatchDepositRequestCoin {
-      // EdDSA public key of the coin being deposited.
-      coin_pub: EddsaPublicKey;
+    interface BatchDepositRequestReceipt {
+      // EdDSA public key of the receipt being deposited.
+      receipt_pub: EddsaPublicKey;
 
-      // Hash of denomination RSA key with which the coin is signed.
+      // Hash of denomination RSA key with which the receipt is signed.
       denom_pub_hash: HashCode;
 
-      // Donau's unblinded RSA signature of the coin.
+      // Donau's unblinded RSA signature of the receipt.
       ub_sig: DonationUnitSignature;
 
       // Signature over `TALER_DonauDepositRequestPS`, made by the customer 
with the
-      // `coin's private key <coin-priv>`.
-      coin_sig: EddsaSignature;
+      // `receipt's private key <receipt-priv>`.
+      receipt_sig: EddsaSignature;
     }
 
-  The deposit operation succeeds if the coin is valid for making a deposit and
+  The deposit operation succeeds if the receipt is valid for making a deposit 
and
   has enough residual value that has not already been deposited or melted.
 
   .. ts:def:: BatchDepositSuccess
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 8eb38a89..968b80c5 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -57,7 +57,10 @@ possibly by using HTTPS.
 
 .. http:get:: /config
 
-  Return the protocol version and currency supported by this exchange backend, 
as well as the list of possible KYC requirements.  This endpoint is largely for 
the SPA for AML officers. Merchants should use ``/keys`` which also contains 
the protocol version and currency.
+  Return the protocol version and currency supported by this exchange backend,
+  as well as the list of possible KYC requirements.  This endpoint is largely
+  for the SPA for AML officers. Merchants should use ``/keys`` which also
+  contains the protocol version and currency.
 
   **Response:**
 

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