From f58e345828204e96339d9b50ad650d5236706b29 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Sun, 10 Jan 2021 22:49:29 -0500 Subject: taler-auditor(1): add opts ‘-c’, ‘-L’, ‘-l’, ‘-T’, ‘-v’ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manpages/taler-auditor.1.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/manpages/taler-auditor.1.rst b/manpages/taler-auditor.1.rst index c4b82376..622643fc 100644 --- a/manpages/taler-auditor.1.rst +++ b/manpages/taler-auditor.1.rst @@ -12,9 +12,14 @@ Synopsis ======== **taler-auditor** +[**-c** *FILENAME* | **––config=**\ ‌\ *FILENAME*] [**-h** | **––help**] [**-i**_|_**––internal**] +[**-L** *LOGLEVEL* | **––loglevel=**\ ‌\ *LOGLEVEL*] +[**-l** *FILENAME* | **––logfile=**\ ‌\ *FILENAME*] [**-m** *MASTER_KEY* | **––exchange-key=**\ ‌\ *MASTER_KEY*] +[**-T** *USEC* | **––timetravel**\ \ *USEC*] +[**-v** | **––version**] Description @@ -30,6 +35,10 @@ found in the database. It does NOT check with the bank to see that the incoming and outgoing wire transfers that the bank claims to have matches the exchange’s database. Its options are as follows. +**-c** *FILENAME* \| **––config=**\ ‌\ *FILENAME* + Use the configuration and other resources for the merchant to operate + from *FILENAME*. + **-h** \| **––help** Print short help on options. @@ -37,12 +46,26 @@ matches the exchange’s database. Its options are as follows. Run additional checks that can only performed on the exchange-internal database and not the "safe" replicated database at the auditor. +**-L** *LOGLEVEL* \| **––loglevel=**\ ‌\ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **––logfile=**\ ‌\ *FILENAME* + Send logging output to *FILENAME*. + **-m** *KEY* \| **––exchange-key=**\ ‌\ *KEY* Public master key of the exchange in Crockford base32 encoding, for example as generated by gnunet-ecc -p. If this option is missing, taler-auditor will use the MASTER_PUBLIC_KEY value from the “exchange” section of the configuration. +**-T** *USEC* \| **––timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-v** \| **––version** + Print version information. See Also -- cgit v1.2.3 From 02a00c78cfae37e18c613d606ef24b92df927dc3 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Mon, 11 Jan 2021 00:18:27 -0500 Subject: add subsection "Socket permission details" This reflects the result of an email discussion between FD and CG. --- design-documents/010-exchange-helpers.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/design-documents/010-exchange-helpers.rst b/design-documents/010-exchange-helpers.rst index a2999487..a304d8ec 100644 --- a/design-documents/010-exchange-helpers.rst +++ b/design-documents/010-exchange-helpers.rst @@ -42,6 +42,12 @@ running under a different user ID (UID), creating in effect a software security module. The exchange's HTTP process will be required to interact with those helpers via a UNIX domain socket. +Socket permission details: + +* The socket will be chmod 0620 (u+rw, g+w) regardless of umask. +* That the group is the same group of the crypto helpers must + still be ensured by the operator. + General design details: * The helpers will process requests from the exchange to sign and revoke keys. -- cgit v1.2.3 From be4b567666c0f05a68be01ec20b2e81212a32a2f Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Mon, 11 Jan 2021 00:24:30 -0500 Subject: mention socket perms and same-group requirement This reflects the result of an email discussion between FD and CG. --- taler-exchange-manual.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 2d476711..79a3bdf0 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -234,6 +234,9 @@ integration support. Functionality ^^^^^^^^^^^^^ +The UNIX domain sockets have mode 0620 (u+rw, g+w). The exchange process +MUST be in the same group as the the crypto helper processes. + The two helper processes will create the required private keys, and allow anyone with access to the UNIX domain socket to sign arbitrary messages with the keys or to inform them about a key being revoked. The helper processes -- cgit v1.2.3 From 18cb46b2b6f6588eceaf83e63d1deff87630fd08 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Mon, 11 Jan 2021 02:08:15 -0500 Subject: add link to taler.conf(5) for "duration" values --- taler-exchange-manual.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 79a3bdf0..e470fd89 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -478,7 +478,9 @@ must then have the following options: - ``RSA_KEYSIZE``: How many bits should the RSA modulus (product of the two primes) have for this type of coin. - +See :doc:`taler.conf(5) manpages/taler.conf.5` for information on *duration* values +(i.e. ``DURATION_WITHDRAW`` and ``DURATION_SPEND``above, +and ``OVERLAP_DURATION`` and ``DURATION`` below). Additionally, there are two global configuration options of note: - ``[taler-helper-crypto-rsa/OVERLAP_DURATION]``: What is the overlap of the -- cgit v1.2.3 From 6dcd6ad89ced216e04d1e1074279aabc14be72a7 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Mon, 11 Jan 2021 02:12:01 -0500 Subject: add link to taler.conf(5) for "duration" values (try 2) --- taler-exchange-manual.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index e470fd89..fe3eab6c 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -478,7 +478,7 @@ must then have the following options: - ``RSA_KEYSIZE``: How many bits should the RSA modulus (product of the two primes) have for this type of coin. -See :doc:`taler.conf(5) manpages/taler.conf.5` for information on *duration* values +See :doc:`manpages/taler.conf.5` for information on *duration* values (i.e. ``DURATION_WITHDRAW`` and ``DURATION_SPEND``above, and ``OVERLAP_DURATION`` and ``DURATION`` below). Additionally, there are two global configuration options of note: -- cgit v1.2.3 From 8ab27ec17bc7889f07ab0c1487b46f5d206e8124 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Mon, 11 Jan 2021 02:12:51 -0500 Subject: fix typo: add space after markup --- taler-exchange-manual.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index fe3eab6c..19ca7a48 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -479,7 +479,7 @@ must then have the following options: primes) have for this type of coin. See :doc:`manpages/taler.conf.5` for information on *duration* values -(i.e. ``DURATION_WITHDRAW`` and ``DURATION_SPEND``above, +(i.e. ``DURATION_WITHDRAW`` and ``DURATION_SPEND`` above, and ``OVERLAP_DURATION`` and ``DURATION`` below). Additionally, there are two global configuration options of note: -- cgit v1.2.3 From 99cabcd488e393bc8c7f00c64e6916d108723ece Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Mon, 11 Jan 2021 02:13:24 -0500 Subject: fix typo: indent --- taler-exchange-manual.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 19ca7a48..e75303f4 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -487,7 +487,7 @@ Additionally, there are two global configuration options of note: withdrawal timespan for denomination keys? The value given here must be smaller than any of the ``DURATION_WITHDRAW`` values for any of the coins. -- ``[taler-helper-crypto-rsa/LOOKAHEAD_SIGN]``: For how far into the future +- ``[taler-helper-crypto-rsa/LOOKAHEAD_SIGN]``: For how far into the future should denomination keys be pre-generated? This allows the exchange and auditor operators to download, offline-sign, and upload denomination key signatures for denomination keys that will be used in the future by the -- cgit v1.2.3 From 675294b4f107a2026fdc3858850323ff10e6f2bf Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Mon, 11 Jan 2021 03:08:06 -0500 Subject: add several links to various docs/manpages --- taler-exchange-manual.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index e75303f4..879f9ad2 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -441,6 +441,7 @@ permissions. Those permissions are only required for this step (which may have to be repeated when upgrading a deployment). Afterwards, during normal operation, permissions to ``CREATE`` or ``ALTER`` tables are not required by any of the Taler exchange processes and thus should not be granted. +For more information, see :doc:`manpages/taler-exchange-dbinit.1`. .. _Coins-denomination-keys: @@ -654,9 +655,8 @@ follows to enable a wire account: $ taler-exchange-offline enable-account payto://iban/CH9300762011623852957 The resulting JSON output must be uploaded to the exchange using -``taler-exchange-offline upload``. For details, see the man -page on ``taler-exchange-offline``. -ttn: please turn this into a link! +``taler-exchange-offline upload``. +For details, see :doc:`manpages/taler-exchange-offline.1`. .. _Wire-fee-structure: @@ -822,7 +822,7 @@ to provision the signatures to the exchange. At this point, the exchange will be able to use those keys, but wallets and merchants may not yet trust them! Thus, the next step is for the auditor to affirm that they are auditing this exchange. Details about -this are described in the auditor manual (ttn: add link, please!). +this are described in :doc:`taler-auditor-manual`. The simplistic (without using offline keys for the auditor) way to do this would be: @@ -831,6 +831,8 @@ to do this would be: $ taler-auditor-offline download sign upload +For more information, see :doc:`manpages/taler-auditor-offline.1`. + Private key storage ------------------- -- cgit v1.2.3 From ee35dab4b592b720138976d1fef65ca8de6d7c36 Mon Sep 17 00:00:00 2001 From: Stefan Kügel Date: Mon, 11 Jan 2021 22:14:02 +0100 Subject: Changes applied according to ttn's recommendations --- design-documents/012-fee-schedule-metrics.rst | 72 +++++++++++++-------------- 1 file changed, 34 insertions(+), 38 deletions(-) diff --git a/design-documents/012-fee-schedule-metrics.rst b/design-documents/012-fee-schedule-metrics.rst index efcebd73..506833ba 100644 --- a/design-documents/012-fee-schedule-metrics.rst +++ b/design-documents/012-fee-schedule-metrics.rst @@ -1,5 +1,5 @@ -Fees schedule and fee metrics -############################# +Design Doc 012: Fees schedule and fee metrics +############################################# .. warning:: @@ -8,41 +8,54 @@ Fees schedule and fee metrics Summary ======= -This chapter discusses considerations for fees from different points of view (Exchange operators, customer/users, and sellers/merchants. +This chapter discusses considerations for fees from different points of view (Exchange operators, customers/users, and sellers/merchants). Motivation ========== -Fees are necessary for covering costs that Exchange operators bear for offering their services established in-house or outsourced in a data center: Variable costs (e.g. electricity and wire fees for every wired transaction to bank accounts) and expenses of constant height for hardware, company assets, marketing and staff, and so forth. They will allocate these costs to customers. The Taler protocol therefore offers different types of fees for each type of transaction that may appear in the transaction cycle. There are six fee types available which can be chosen by the Exchange operator, defining their specific value within the limits given by the protocol. +Fees are necessary for covering costs that Exchange operators bear for offering their services established in-house or outsourced in a data center: Variable costs (e.g. electricity and wire fees for every wired transfer to bank accounts) and fixed-cost expenditures for hardware, company assets, marketing and staff, and so forth. They will allocate these costs to customers. The Taler protocol therefore offers different types of fees for each type of transaction that may appear in the transaction cycle. There are six fee types available for selection by the Exchange operator, each with a specific value within the limits given by the protocol. The protocol itself is subject to the legal framework established by (supra-)national regulatory authorities. Any coin that has been generated or that is used (deposited) or refreshed can be charged with an applicable fee type. In addition to this, every wired amount of money can be charged with a wire fee. The six fee types are named as 'Withdrawal', 'Deposit', 'Refresh', 'Refund', 'Wire fee' and 'Closing'. The fee type 'Closing' is used for allocating costs that arise from an uncompleted withdrawal transaction when an amount of fiat money has to be wired back from the Exchange's escrow account to the bank account of origin. -Fee types and their underlying metrics are not only due to cover real costs in the long run, but also to reward users for their economic behaviour, to prevent misuse, and to allow Exchange operators to gain certain income and most probably profits. Exchange operators are thus determining the combination of fee types and the height of each fee for every denomination of coins. Any chosen denomination (constant nominal value of coins preset by the operator by means of the Denomination key) will subsequently come along with a variety of fee types and their individually specified height. +Fee types and their underlying metrics are intended not only to cover real costs in the long run, but also to reward users for their economic behaviour, to prevent misuse, and to allow Exchange operators to gain certain income and most probably profits. Exchange operators are thus determine the combination of fee types and the amount of each fee for every denomination of coins. Any chosen denomination (constant nominal value of coins preset by the operator by means of the Denomination key) will subsequently come along with a variety of fee types and their individually specified amounts. Proposed Solution ================= +The Taler protocol offers the following fee types: + +1. 'Withdrawal': For each successful withdrawal from the checking account, per coin +2. 'Deposit': For spending, per coin +3. 'Refresh': Per coin for + a. Refresh transactions for receiving change + b. Refresh of coins at the end of their validity + c. Abort of transactions due to network failure + d. Refund +4. 'Refund': For refunds or in case of contract cancellation by seller, per coin +5. 'Wire fee': For aggregated amounts wired by the Exchange to the merchant's checking account, per wire transfer +6. 'Closing': In case that a withdrawal process could not be accomplished (the users' wallet did not withdraw the value from the reserve), per wire transfer from the Exchange's escrow account to the account of origin + Fee schedule -============== +============ -Whereas the Taler protocol determines types of fees, Exchange operators determine the upper and lower limits of fees using parameters. Once they have set the fee height per denomination, the algorithm of the Taler payment system will allocate costs automatically to every generated coin respectively to a wired amount. +Whereas the Taler protocol determines types of fees, Exchange operators determine the upper and lower limits of fees using parameters. Once they have set the fee amount per denomination, the algorithm of the Taler payment system will allocate costs automatically to every generated coin respective to a wired amount. The fee structure and its underlying metrics are also bound to rules and expectations of financial regulatory authorities like the German Federal Financial Supervisory Authority (Bundesanstalt für Finanzdienstleistungsaufsicht BaFin). Changes to the fee structure are therefore eligible only when they are in accordance with national or international laws and directives. -Fees chosen by Exchange operators have to be explained to the users by means of comprehensive Terms and conditions of services that rule out the different and heights of fees and how they are calculated. Costs for wired amounts within the banking system (IBAN transfers to the Exchange's escrow account for the withdrawal transaction; IBAN: International Banking Account Number) have to be covered by users, so additionally Terms and conditions of their banks may be effective, too. These Terms of banking services are not part of the Taler payment system, nevertheless Exchange operators should make users aware of this fact, that each wired transactions may cause costs on their expense. +Fees chosen by Exchange operators have to be explained to the users by means of comprehensive Terms and conditions of services that describe the fee types and amounts of fees and how they are calculated. Costs for wired amounts within the banking system (IBAN transfers to the Exchange's escrow account for the withdrawal transaction; IBAN: International Banking Account Number) have to be covered by users, so additionally Terms and conditions of their banks may be effective, too. These Terms of banking services are not part of the Taler payment system, nevertheless Exchange operators should inform users that each wired transfer may incur a fee. 1. Obligations of Exchange operators ---------------------------------------- +------------------------------------ -Exchange operators have to adhere to the fee schedule. Otherwise they can lose their interface access, have their certification revoked and, moreover, even become liable for damages. For each transaction type there is one specific fee type. Exchange operators set the height of fees. If a fee type is set to a value of 0, this fee type will not contribute to the operator's income from fees. +Exchange operators have to adhere to the fee schedule. Otherwise they can lose their interface access, have their certification revoked and, moreover, even become liable for damages. For each transaction type there is one specific fee type. Exchange operators set the fee amount. If a fee type is set to a value of 0, this fee type will not contribute to the operator's income from fees. -Three fee types ('Wire fee', 'Closing' and 'Recoup') will cause costs for Exchange operators due to wire transfers to accounts wired by banks. Therefore, operators must find suitable ways to have these costs covered by customers. +Two fee types ('Wire fee', 'Closing') and the 'Recoup' protocol will cause costs for Exchange operators due to wire transfers to accounts wired by banks. Therefore, operators must find suitable ways to have these costs covered by customers. -The 'Recoup' protocol does not allow Exchange operators to set any fee height, because reimbursing funds from an Exchange that is about to cease its activity must always be at zero costs for the users. Wiring fees in the case of 'Recoup' have to be entirely covered by Exchange operators instead. +The 'Recoup' protocol does not allow Exchange operators to set any fee amount, because reimbursing funds from an Exchange that is about to cease its activity must always be at zero cost for the user. Wiring fees in the case of 'Recoup' have to be entirely covered by Exchange operators instead. -Setting all of the six fee types to 0 means would simply the payment system and make it more attractive to users. However, Exchange operators need effective counter-measures against possible misuse. Transactions that are abundantly often repeated by malicious users are driving costs, thus harming operators. Making these transactions costly to those who trigger them intentionally is the only way to solve this issue. +Setting all of the six fee types to 0 means would simplify the payment system and make it more attractive to users. However, Exchange operators need effective counter-measures against possible misuse. Transactions that are abundantly often repeated by malicious users drive up costs, thus harming operators. Making these transactions costly to those who trigger them intentionally is the only way to solve this issue. -For example, if the Exchange operator sets the 'Refresh' fee at the level of the specific costs incurred for this transaction type, malicious cost driving with refresh does at least not damage the exchange, but only charges those users who have their coins refreshed particularly frequently (see detailed below). +For example, if the Exchange operator sets the 'Refresh' fee at the level of the specific costs incurred for this transaction type, malicious cost driving with refresh at least does not damage the exchange, but only charges those users who have their coins refreshed particularly frequently (see detailed below). Operators agree that their audit reports report income from fees to the auditors and, accordingly, to the supervisory authorities. Fees on coins at set the time they are issued and cannot be changed afterwards. According to the Taler protocol, fees on bank transfers can only be adjusted annually and are set by the operator for at least 2 years in the future. Thanks to this constant fee, merchants can better plan costs to be added and include them in their sales prices. @@ -51,7 +64,7 @@ Terms and conditions of every Exchange must also clearly indicate to the user th A private bank that hosts an Exchange and normally charges its customers for IBAN transfers has the option of waiving the applying fees for their customers when they are withdrawing from their own checking accounts into Taler wallets. 2. Buyer's obligations ------------------------ +---------------------- Prior to making a first withdrawal from an Exchange users are required to read and confirm the Terms and conditions of the relevant Exchange. This step is mandatory when changes to Terms and conditions take place. Users accept Terms and conditions by confirming them in the mobile application or on the web. Terms and conditions also require users to accept possible losses of funds in wallets through 'Refresh' fees, which can be eventually charged by Exchange operators. @@ -62,7 +75,7 @@ In accordance with the Terms and conditions, the users agree not to make any cla Furthermore, according to the Terms and conditions, users must accept that the IBAN transfer from the users' personal checking account to the Exchange's escrow account may incur costs depending on the contract with their banks. These costs are not related to the Taler payment system and cannot be influenced by it. 3. Obligations of merchants/sellers ------------------------------------- +----------------------------------- Normally, a plurality of buyers' spending transactions is summed up to one aggregated amount of revenue and wired to the receiving checking account of the merchant. Merchants can set the frequency by which these aggregated amounts are wired. Every wire transfer imposes costs on the Exchange operator collected by the operator's bank for having the amount wired. Therefore, the Exchange operator will tend to charge the 'Wire fee' to the sellers for this transaction type, as the sellers are the ones causing the aggregated transfer and not the buyers. If from a seller's point of view an Exchange operator has set the 'Wire fee' too high, the seller can make use of the Taler Merchant software and determine the so-called amortization factor to add all or part of the 'Wire fee' to the amount payable by customers who deposit coins from their wallets funded via this Exchange. @@ -71,7 +84,7 @@ During the withdrawal process, the wallet shows to the buyer the complete fee sc Given the case that sellers enter incorrect account data for their own checking account, they are solely liable for any resulting damage and not the Exchange operator. Sellers bear the risk of a loss of value or even a total loss of their revenue if they enter a wrong IBAN for the transfer of their revenue, although syntactically correct. Similarly, the sellers alone bear charges due to an incorrect receiving account number or other posting errors that they cause and for which manual routing becomes necessary (e.g. in the case of lapsed accounts). 4. Technical framework conditions for the collection of fees -------------------------------------------------------------- +------------------------------------------------------------ Fees are charged per coin or per wire transfer. The number of coins at withdrawal usually increases logarithmically with the amount represented. Fees can be applied to both flow quantities (e.g. coins moved at withdrawal and deposit transactions) and static quantities (e.g. coins stored in wallets). The fees on coins may differ depending on the time of issuance of a coin and depending on the value of a coin. They are fixed for each coin with its time of issuance, so they cannot be changed subsequently during their validity by the Exchange operator. @@ -80,27 +93,10 @@ During the entire period of validity, all Denomination keys and the selected fee The refresh transaction is automatically triggered by the wallet software 3 months before the end of the validity of a coin. Especially if Exchange operators charge refresh fees, they have to point out this automatic feature to the users in their Terms and conditions. -Fee types -=========== - -The Taler protocol offers the following fee types: - -1. 'Withdrawal': For each successful withdrawal from the checking account, per coin -2. 'Deposit': For spending, per coin -3. 'Refresh': Per coin for - a. Refresh transactions for receiving change - b. Refresh of coins at the end of their validity - c. Abort of transactions due to network failure - d. Refund -4. 'Refund': For refunds or in case of contract cancellation by seller, per coin -5. 'Wire fee': For aggregated amounts wired by the Exchange to the merchant's checking account, per wire transfer -6. 'Closing': In case that a withdrawal process could not be accomplished (the users' wallet did not withdraw the value from the reserve), per wire transfer from the Exchange's escrow account to the account of origin - - -Effects of fee types on Exchange operators, buyers and sellers ------------------------------------------------------------------- +Effects of fee types on users: Buyers, Exchange operators, and sellers +====================================================================== -Each of the above fee types is now considered viewed from the perspective of the buyer, the exchange operator, and the seller: +Each of the above mentioned fee types is now considered viewed from the perspective of the buyer, the exchange operator, and the seller: * 'Withdrawal' from the buyer's point of view: @@ -124,7 +120,7 @@ During deposit, the Exchange logic compares the public key of each coin with the * 'Deposit' from the seller's point of view: -If an Exchange operator charges relatively high deposit fees, sellers have a means to correlate the fee height. As pointed out before, a seller must bear deposit fees, but only up to the maximum determined by the variable default_max_deposit_fee, which every seller specifies individually. +If an Exchange operator charges relatively high deposit fees, sellers have a means to correlate the fee amount. As pointed out before, a seller must bear deposit fees, but only up to the maximum determined by the variable default_max_deposit_fee, which every seller specifies individually. Deposit fees will also affect refund transactions, for example when a rebate is given by the seller to the customer. Only in the case of a complete withdrawal from the contract by the seller the refund transaction exempts the buyers from deposit fees. Then, the refund transaction incurs the refresh fee only that would be borne by the buyers. If the seller's refund is partly, only the seller's deposit fee is waived, which means from the buyer's perspective a partly refunded purchase with coins signed at an Exchange with high deposit fees is becoming less attractive. In other words: Deposit fees exceeding the seller's maximum value will be borne by the buyers, making the rebate worse from the buyers' perspective. -- cgit v1.2.3 From e5a5291bd9aa4aef72029556be79d132029d2ed4 Mon Sep 17 00:00:00 2001 From: MS Date: Tue, 12 Jan 2021 17:06:31 +0100 Subject: nexus: API to query raw XML messages. --- libeufin/api-nexus.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index ce93f8b1..2d26a227 100644 --- a/libeufin/api-nexus.rst +++ b/libeufin/api-nexus.rst @@ -634,6 +634,35 @@ to the real bank. nexusBankAccountId: string; } + +.. http:get:: /bank-connections/{connId}/messages + + List *some* details of all the ISO2022 messages gotten from the bank. It + responds with a list of the following elements: + + .. code-block:: ts + + interface BankMessageInfo { + + // the message type, typically how the containing layer + // (Ebics, for example) would label this information. For + // Camt.053 types, this value is "C53". + code: string; + + // the unique identifier of the message. + messageId: string; + + // bytes length of the message. + length: number; + } + + + +.. http:get:: /bank-connections/{connId}/messages/{msgId} + + Return the ISO20022 XML corresponding to ``msgId``. + + Facades ------- -- cgit v1.2.3 From 1f3cc8db0eb61d9cac8c00433cda58d122771eb4 Mon Sep 17 00:00:00 2001 From: Stefan Kügel Date: Tue, 12 Jan 2021 18:47:24 +0100 Subject: Including the remainder of corrections to the Design document 012 'Fee schedule' --- design-documents/012-fee-schedule-metrics.rst | 109 +++++++++++++------------- 1 file changed, 55 insertions(+), 54 deletions(-) diff --git a/design-documents/012-fee-schedule-metrics.rst b/design-documents/012-fee-schedule-metrics.rst index 506833ba..612393d7 100644 --- a/design-documents/012-fee-schedule-metrics.rst +++ b/design-documents/012-fee-schedule-metrics.rst @@ -15,7 +15,7 @@ Motivation Fees are necessary for covering costs that Exchange operators bear for offering their services established in-house or outsourced in a data center: Variable costs (e.g. electricity and wire fees for every wired transfer to bank accounts) and fixed-cost expenditures for hardware, company assets, marketing and staff, and so forth. They will allocate these costs to customers. The Taler protocol therefore offers different types of fees for each type of transaction that may appear in the transaction cycle. There are six fee types available for selection by the Exchange operator, each with a specific value within the limits given by the protocol. The protocol itself is subject to the legal framework established by (supra-)national regulatory authorities. -Any coin that has been generated or that is used (deposited) or refreshed can be charged with an applicable fee type. In addition to this, every wired amount of money can be charged with a wire fee. The six fee types are named as 'Withdrawal', 'Deposit', 'Refresh', 'Refund', 'Wire fee' and 'Closing'. The fee type 'Closing' is used for allocating costs that arise from an uncompleted withdrawal transaction when an amount of fiat money has to be wired back from the Exchange's escrow account to the bank account of origin. +Any coin that has been generated or that is used (deposited) or refreshed can be charged with an applicable fee type. In addition to this, every wired amount of money can be charged with a wire fee. The six fee types are named as **Withdrawal**, **Deposit**, **Refresh**, **Refund**, **Wire fee** and **Closing**. The fee type 'Closing' is used for allocating costs that arise from an uncompleted withdrawal transaction when an amount of fiat money has to be wired back from the Exchange's escrow account to the bank account of origin. Fee types and their underlying metrics are intended not only to cover real costs in the long run, but also to reward users for their economic behaviour, to prevent misuse, and to allow Exchange operators to gain certain income and most probably profits. Exchange operators are thus determine the combination of fee types and the amount of each fee for every denomination of coins. Any chosen denomination (constant nominal value of coins preset by the operator by means of the Denomination key) will subsequently come along with a variety of fee types and their individually specified amounts. @@ -24,16 +24,16 @@ Proposed Solution The Taler protocol offers the following fee types: -1. 'Withdrawal': For each successful withdrawal from the checking account, per coin -2. 'Deposit': For spending, per coin -3. 'Refresh': Per coin for +1. **Withdrawal**: For each successful withdrawal from the checking account, per coin +2. **Deposit**: For spending, per coin +3. **Refresh**: Per coin for a. Refresh transactions for receiving change b. Refresh of coins at the end of their validity c. Abort of transactions due to network failure d. Refund -4. 'Refund': For refunds or in case of contract cancellation by seller, per coin -5. 'Wire fee': For aggregated amounts wired by the Exchange to the merchant's checking account, per wire transfer -6. 'Closing': In case that a withdrawal process could not be accomplished (the users' wallet did not withdraw the value from the reserve), per wire transfer from the Exchange's escrow account to the account of origin +4. **Refund**: For refunds or in case of contract cancellation by seller, per coin +5. **Wire fee**: For aggregated amounts wired by the Exchange to the merchant's checking account, per wire transfer +6. **Closing**: In case a withdrawal process could not be accomplished (the user's wallet did not withdraw the value from the reserve), per wire transfer from the Exchange's escrow account to the account of origin Fee schedule ============ @@ -55,20 +55,20 @@ The 'Recoup' protocol does not allow Exchange operators to set any fee amount, b Setting all of the six fee types to 0 means would simplify the payment system and make it more attractive to users. However, Exchange operators need effective counter-measures against possible misuse. Transactions that are abundantly often repeated by malicious users drive up costs, thus harming operators. Making these transactions costly to those who trigger them intentionally is the only way to solve this issue. -For example, if the Exchange operator sets the 'Refresh' fee at the level of the specific costs incurred for this transaction type, malicious cost driving with refresh at least does not damage the exchange, but only charges those users who have their coins refreshed particularly frequently (see detailed below). +For example, if the Exchange operator sets the 'Refresh' fee at the level of the specific costs incurred for this transaction type, malicious cost driving with refresh at least does not damage the exchange, but only charges those users who have their coins refreshed particularly frequently (see details below). -Operators agree that their audit reports report income from fees to the auditors and, accordingly, to the supervisory authorities. Fees on coins at set the time they are issued and cannot be changed afterwards. According to the Taler protocol, fees on bank transfers can only be adjusted annually and are set by the operator for at least 2 years in the future. Thanks to this constant fee, merchants can better plan costs to be added and include them in their sales prices. +Operators agree that their audit reports report income from fees to the auditors and, accordingly, to the supervisory authorities. Fees on coins are set the time they are issued and cannot be changed afterwards. According to the Taler protocol, fees on bank transfers can only be adjusted annually and are set by the operator for at least 2 years in the future. Thanks to this constant fee, merchants can better plan costs to be added and include them in their sales prices. Terms and conditions of every Exchange must also clearly indicate to the user that if they refuse to save copies of their Taler coins (with a backup tool like e.g. "Anastasis") they are risking a total loss of coin ownership. -A private bank that hosts an Exchange and normally charges its customers for IBAN transfers has the option of waiving the applying fees for their customers when they are withdrawing from their own checking accounts into Taler wallets. +A private bank that hosts an Exchange and normally charges its customers for IBAN transfers has the option of waiving the applicable fees for their customers when they withdraw from their own checking accounts into Taler wallets. 2. Buyer's obligations ---------------------- -Prior to making a first withdrawal from an Exchange users are required to read and confirm the Terms and conditions of the relevant Exchange. This step is mandatory when changes to Terms and conditions take place. Users accept Terms and conditions by confirming them in the mobile application or on the web. Terms and conditions also require users to accept possible losses of funds in wallets through 'Refresh' fees, which can be eventually charged by Exchange operators. +Prior to making the first withdrawal from an exchange users are required to read and confirm the Terms and conditions of the relevant Exchange. This step is mandatory when changes to Terms and conditions take place. Users accept Terms and conditions by confirming them in the mobile application or on the web. Terms and conditions also require users to accept possible losses of funds in wallets through 'Refresh' fees, which can be eventually charged by Exchange operators. -All charge types and amounts are displayed to users prior to each withdrawal. Specific transaction-related transaction fees that users would have to pay are always displayed by the wallet as part of the interactive transaction process. Wire fees are also shown to the users. The fee type 'Wire fee' allows merchants (sellers) to split the charged amount when they deem an Exchange's wire fee to be too high and pass on the split charge to buyers and bear the remainder. The respective amount of the 'Wire fee' is set by the merchant using the variable wire_fee_amortization and will be automatically applied. +All charge types and amounts are displayed to users prior to each withdrawal. Specific transaction-related transaction fees that users would have to pay are always displayed by the wallet as part of the interactive transaction process. Wire fees are also shown to the users. The fee type 'Wire fee' allows merchants (sellers) to split the charged amount when they deem an Exchange's wire fee to be too high and pass on the split charge to buyers, bearing the remainder. The respective amount of the 'Wire fee' is set by the merchant using the variable ``wire_fee_amortization`` and will be automatically applied. In accordance with the Terms and conditions, the users agree not to make any claim for damages against the payment system or the Exchange operator due to losses incurred by them as a result of theft or self-inflicted failure to secure the coins in the Taler wallet. @@ -81,107 +81,108 @@ Normally, a plurality of buyers' spending transactions is summed up to one aggre During the withdrawal process, the wallet shows to the buyer the complete fee schedule and indicates the 'Wire fee' in case this fee is really charged. However, if a seller takes over the wire fee charge instead of the customers, the customers' wallets will no longer show a wire fee for that seller. These sellers thus render the fee schedule clearer for their customers, but certainly will have the wire fee calculated with their sales prices. -Given the case that sellers enter incorrect account data for their own checking account, they are solely liable for any resulting damage and not the Exchange operator. Sellers bear the risk of a loss of value or even a total loss of their revenue if they enter a wrong IBAN for the transfer of their revenue, although syntactically correct. Similarly, the sellers alone bear charges due to an incorrect receiving account number or other posting errors that they cause and for which manual routing becomes necessary (e.g. in the case of lapsed accounts). +Sellers who enter incorrect account data for their own checking account are solely liable for any resulting damage and not the Exchange operator. Sellers bear the risk of a loss of value or even a total loss of their revenue if they enter a wrong IBAN for the transfer of their revenue, although syntactically correct. Similarly, the sellers alone bear charges due to an incorrect receiving account number or other posting errors that they cause and for which manual routing becomes necessary (e.g. in the case of lapsed accounts). 4. Technical framework conditions for the collection of fees ------------------------------------------------------------ -Fees are charged per coin or per wire transfer. The number of coins at withdrawal usually increases logarithmically with the amount represented. Fees can be applied to both flow quantities (e.g. coins moved at withdrawal and deposit transactions) and static quantities (e.g. coins stored in wallets). The fees on coins may differ depending on the time of issuance of a coin and depending on the value of a coin. They are fixed for each coin with its time of issuance, so they cannot be changed subsequently during their validity by the Exchange operator. +Fees are charged per coin or per wire transfer. The number of coins at withdrawal usually increases logarithmically with the amount represented. Fees can be applied to both flow quantities (e.g. coins moved at withdrawal and deposit transactions) and static quantities (e.g. coins stored in wallets). The fees on coins may differ depending on the time of issuance of a coin and depending on the value of a coin. They are fixed for each coin at its time of issuance, and cannot be changed subsequently during their validity by the Exchange operator. During the entire period of validity, all Denomination keys and the selected fee types shall remain valid. Each fee type is always managed as a variable in the exchange interface even if the amount is 0 units. -The refresh transaction is automatically triggered by the wallet software 3 months before the end of the validity of a coin. Especially if Exchange operators charge refresh fees, they have to point out this automatic feature to the users in their Terms and conditions. +The refresh transaction is automatically triggered by the wallet software 3 months before the end of the validity of a coin. Especially if Exchange operators charge 'Refresh' fees, they have to point out this automatic feature to the users in their Terms and conditions. Effects of fee types on users: Buyers, Exchange operators, and sellers ====================================================================== -Each of the above mentioned fee types is now considered viewed from the perspective of the buyer, the exchange operator, and the seller: +We now consider each of the fee types, viewed from the perspective of the buyer, the Exchange operator, and the seller: -* 'Withdrawal' from the buyer's point of view: +* **Withdrawal** from the buyer's point of view: -Anyone who wants to load Taler wallets with coins must initiate a wire transfer from the own checking account to the Exchange operator's escrow account to let the Exchange fund a reserve which can be subsequently withdrawn by the wallet. Costs for the wire transfer may be incurred according to the user's contract with the bank. In addition to these potentially incurred costs, the withdrawal fee could be charged for each coin withdrawn into the wallet. Even though many bank customers are already accustomed to wire transfer charges, the withdrawal fee acts like a loss of purchasing power even before intended transactions take place. Buyers are made aware this loss when being shown all types of fees at withdrawal. Once buyers become aware that they will have to pay the cost for each coin generated, they might prefer to have as few high-denomination coins as possible withdrawn into their wallets. +Anyone who wants to load Taler wallets with coins must initiate a wire transfer from their own checking account to the Exchange operator's escrow account to let the Exchange fund a reserve which can be subsequently withdrawn by the wallet. Costs for the wire transfer may be incurred according to the user's contract with the bank. In addition to these potentially incurred costs, the withdrawal fee could be charged for each coin withdrawn into the wallet. Even though many bank customers are already accustomed to wire transfer charges, the withdrawal fee acts like a loss of purchasing power even before intended transactions take place. Buyers are made aware of this loss when being shown all fee types at withdrawal. Once buyers become aware that they will have to pay the cost for each coin generated, they might prefer to have as few high-denomination coins as possible withdrawn into their wallets. -* 'Withdrawal' from the Exchange operator's point of view: +* **Withdrawal** from the Exchange operator's point of view: -A fee on each coin generated would indeed hit all electronic coins withdrawn from an exchange operator and allocate costs necessary for their generation over all coins signed for the first time, but would not prevent abuse through other transactions like intentionally often triggered refresh or refund and would also discriminate against those users who withdraw and deposit many smaller denominations. Furthermore, buyers using coins with higher denominations could increase the exchange operator's costs by increasing refresh transactions. Overall, the cost increases are marginally small, though. +A fee on each coin generated would indeed affect all electronic coins withdrawn from an exchange operator and allocate costs necessary for their generation over all coins signed for the first time, but would not prevent abuse through other transactions like intentionally often-triggered refresh or refund, and would also discriminate against those users who withdraw and deposit many smaller denominations. Furthermore, buyers using coins with higher denominations could increase the exchange operator's costs by increasing refresh transactions. Overall, the cost increases are marginally small, though. -* 'Withdrawal' from the seller's point of view: +* **Withdrawal** from the seller's point of view: While withdrawal fees do not burden sellers, withdrawal fees are imposing a threshold for their customers (see argumentation above). Sellers would even prefer to include the costs of generating coins in their selling prices and hide it from customers. However, the coins generated for customers during the withdrawal process do not correspond with the sellers in any way. -* 'Deposit' from the buyer's point of view: +* **Deposit** from the buyer's point of view: -Although customers are triggering the deposit request to finalize their purchase, it is always the seller who has to bear the deposit fee per coin - but only up to a maximum value determined by the seller (using the variable default_max_deposit_fee). The remainder of the deposit fee exceeding this maximum value has to be paid by the respective buyer. Deposit fees could theoretically be used to distribute all costs that Exchange operators have to bear. This would mean that all costs will be allocated to all coins deposited for buying goods and services. Usually, buyers can easily understand that a fee is charged on deposited coins. This is why 'Deposit' should be taken into consideration as an important and easy to propagate fee, not only from a buyers' perspective, but also from the operators' point of view. +Customers give a merchant the right to deposit coins in return for merchandise, and sellers trigger the deposit request. It is always the seller who has to bear the deposit fee per coin - but only up to a maximum value determined by the seller (using the variable ``default_max_deposit_fee``). The remainder of the deposit fee exceeding this maximum value has to be paid by the respective buyer. Deposit fees could theoretically be used to distribute all costs that Exchange operators have to bear. This would mean that all costs will be allocated to all coins deposited for buying goods and services. Usually, buyers can easily understand that a fee is charged on deposited coins. This is why 'Deposit' should be taken into consideration as an important and easy to propagate fee, not only from a buyers' perspective, but also from the operators' point of view. -* 'Deposit' from the Exchange operator's point of view: +* **Deposit** from the Exchange operator's point of view: During deposit, the Exchange logic compares the public key of each coin with the keys stored in an array in the Exchange's Postgres database and examines each coin to determine whether it is redeemed for payment for the first time. This process consumes little energy and adds no additional cost. For Exchange operators, this marginally small cost factor can only become significant when there is a very high amount of deposit transactions to encounter (e.g. at large web-shops). Deposit fees, above all, represent the most important source of income for the Exchange operator and can easily be collected over all coins used. -* 'Deposit' from the seller's point of view: +* **Deposit** from the seller's point of view: -If an Exchange operator charges relatively high deposit fees, sellers have a means to correlate the fee amount. As pointed out before, a seller must bear deposit fees, but only up to the maximum determined by the variable default_max_deposit_fee, which every seller specifies individually. +If an Exchange operator charges relatively high deposit fees, sellers have a means to set a boundary for the deposit fee amount and split it in two amounts. As pointed out before, a seller must bear deposit fees, but only up to the maximum determined by the variable ``default_max_deposit_fee``, which every seller specifies individually. -Deposit fees will also affect refund transactions, for example when a rebate is given by the seller to the customer. Only in the case of a complete withdrawal from the contract by the seller the refund transaction exempts the buyers from deposit fees. Then, the refund transaction incurs the refresh fee only that would be borne by the buyers. If the seller's refund is partly, only the seller's deposit fee is waived, which means from the buyer's perspective a partly refunded purchase with coins signed at an Exchange with high deposit fees is becoming less attractive. In other words: Deposit fees exceeding the seller's maximum value will be borne by the buyers, making the rebate worse from the buyers' perspective. +Deposit fees will also affect refund transactions, for example when a rebate is given by the seller to the customer. Only in the case of a complete withdrawal from the contract by the seller does the refund transaction exempt the buyer from the deposit fee. In that case, the refund transaction incurs the 'Refresh' fee portion borne by the buyers. If the seller's refund is partial, only the seller's deposit fee is waived, which means from the buyer's perspective a partially refunded purchase with coins signed at an Exchange with high deposit fees becomes less attractive. In other words: Deposit fees exceeding the seller's maximum value will be borne by the buyers, making the rebate worse from the buyers' perspective. -Generally, sellers want to ensure that -(1) the exchange selected by the buyers complies with the regulatory requirements of the supervisory authorities (e.g. BaFin) and with anti-money laundering laws (AML), -(2) if paying is in EURO the exchange operates in the SEPA currency area, and +Generally, sellers want to ensure that: +(1) the exchange selected by the buyers complies with the regulatory requirements of the supervisory authorities (e.g. BaFin) and with anti-money laundering laws (AML); +(2) if paying is in EUR, the exchange operates in the SEPA currency area; and (3) the fees of the selected exchange are within the limits of what the seller sets using its maximum deposit fee values (and wire fee maximum values as described below). -* 'Refresh' from the buyer's point of view: +* **Refresh** from the buyer's point of view: -Refresh fees are mostly caused by the generation of fresh coins as change for a coin of higher denomination that was redeemed for a smaller price that had to be paid: The payment amount was paid with a coin of a higher denomination, subsequently the wallet receives coins with denominations that add up to the difference. The refresh fee for the change booking is therefore only ever charged for one coin used and is marginally low from the buyer's point of view. Refresh also occurs together with refund transactions (a refresh transaction will always be triggered subsequently to discounting or a cancellation of purchase contracts). Less often are refresh transactions due to the expiration of coins or because of transaction aborts after network errors. The fee on refreshes is charged per coin and will be burdened to buyers. It is intended to deter costs incurred by the Exchange in the event of misuse. Buyers will marginally consider this fee as a small personal burden as a remedy to avoid possible abuse with refreshes triggered off in masses by a harmful party, as its absolute amount per coin is low. +Refresh fees are mostly caused by the generation of fresh coins as change for a coin of higher denomination that was redeemed for a smaller price that had to be paid: The payment amount was paid with a coin of a higher denomination, subsequently the wallet receives coins with denominations that add up to the difference. The 'Refresh' fee for the change booking is therefore only ever charged for one coin used and is marginally low from the buyer's point of view. Refresh also occurs together with refund transactions (a refresh transaction will always be triggered subsequently to discounting or a cancellation of purchase contracts). Less often are refresh transactions due to the expiration of coins or because of transaction aborts after network errors. The fee on refreshes is charged to buyers, per coin. It is intended to deter costs incurred by the Exchange in the event of misuse. Buyers will marginally consider this fee as a small personal burden as a remedy to avoid possible abuse with refreshes triggered off en masse by a harmful party, as its absolute amount per coin is low. -* 'Refresh' from the Exchange operator's point of view: +* **Refresh** from the Exchange operator's point of view: -As long as there is no abuse with refresh transactions, the Exchange operator has to consider whether to pass on the costs for refreshes directly to the buyers or to cover these costs with another type of fee. Using the refresh fee to cover costs subsequent to intentional abuse means that the originator of malicious refreshes charges all buyers of a targeted Exchange for their regular refresh bookings. While this does not prevent abuse itself, it only makes the transaction type 'Refresh' costly for those who frequently trigger refreshes. In the acute case of abuse, buyers are then charged fees, but the maliciously caused costs at least do not affect the specific Exchange, but all end users who receive signed coins from it. +As long as there is no abuse with refresh transactions, the Exchange operator has to consider whether to pass on the costs for refreshes directly to buyers or to cover these costs with another type of fee. Using the 'Refresh' fee to cover costs subsequent to intentional abuse means that the originator of malicious refreshes charges all buyers of a targeted Exchange for their regular refresh bookings. While this does not prevent abuse itself, it only makes the transaction type 'Refresh' costly for those who frequently trigger refreshes. In the acute case of abuse, buyers are then charged fees, but the maliciously caused costs at least do not affect the specific Exchange, but all end users who receive signed coins from it. -* 'Refresh' from the seller's point of view: +* **Refresh** from the seller's point of view: -Refresh transactions do not directly affect sellers, but the refund transaction does (see below here). +Refresh transactions do not directly affect sellers, but the refund transaction does (see below). -* 'Refund' from the buyer's point of view: +* **Refund** from the buyer's point of view: -In contrast to the refresh fee type, the sellers - and not the buyers - are triggering the refund booking. If an Exchange charges the refund fee type, the already deposited coins of the buyers would be charged with this fee in case of a partial refund due to discounting after the conclusion of the purchase contract. Only in case of a full refund, the coins of the buyers will be relieved from deposit fees, but then they will be charged with the refresh fee, if the fee schedule of the Exchange chosen by the buyers levies the refresh fee. Normally, it lies within the seller's responsibility to give the reason for a discount or rebate. From the buyers' point of view, therefore, the sellers should legitimately bear this fee. +In contrast to the 'Refresh' fee type, the sellers -- and not the buyers -- trigger the refund booking. If an Exchange charges the 'Refund' fee type, the already deposited coins of the buyers would be charged with this fee in case of a partial refund due to discounting after the conclusion of the purchase contract. Only in case of a full refund, the coins of the buyers will be relieved from deposit fees, but then they will be charged with the 'Refresh' fee, if the fee schedule of the Exchange chosen by the buyers levies the 'Refresh' fee. Normally, it lies within the seller's responsibility to give the reason for a discount or rebate. From the buyers' point of view, therefore, the sellers should legitimately bear this fee. -* 'Refund' from the Exchange operator's point of view: +* **Refund** from the Exchange operator's point of view: -Exchange operators cannot suppress refund postings because they must allow sellers to discount and cancel purchase contracts. A partial refund only partially relieves buyers of their deposit fees. Over time, customers are more likely to avoid such sellers who often have to discount after a contract is signed. Sellers who repeatedly trigger complete refunds, while exempting buyers' coins already deposited with the exchange from deposit fees, burden them with refresh fees. Should an Exchange operator then waive the refresh fee, it would incur costs. To avoid this, the Exchange operator must introduce or increase refresh fees, thereby charging all of its customers more by applying the refresh fee. From the point of view of the Exchange operator, the costs of both the partial and the complete refunds should have to be borne by the sellers, though, so that sellers should feel an incentive to avoid discounts or contract cancellation as far as possible, to fulfill the agreements on goods and services in accordance with the purchase contracts, and likewise to encourage their buyers to trigger returns and contract withdrawals less frequently (with all the economic and ecological effects that this entails, e.g. through frequent arbitrary returns of goods, the delivery and shipping costs, parcel handling and ecological damages that come along with this). +Exchange operators cannot suppress refund postings because they must allow sellers to discount and cancel purchase contracts. A partial refund only partially relieves buyers of their deposit fees. Over time, customers are more likely to avoid such sellers who often have to discount after a contract is signed. Sellers who repeatedly trigger complete refunds, while exempting buyers' coins already deposited with the exchange from deposit fees, burden them with 'Refresh' fees. Should an Exchange operator then waive the 'Refresh' fee, it would incur costs. To avoid this, the Exchange operator must introduce or increase 'Refresh' fees, thereby charging all of its customers more by applying the 'Refresh' fee. From the point of view of the Exchange operator, the costs of both the partial and the complete refunds should have to be borne by the sellers, though, so that sellers should feel an incentive to avoid discounting or contract cancellation as far as possible, to fulfill the agreements on goods and services in accordance with the purchase contracts, and likewise to encourage their buyers to trigger returns and contract withdrawals less frequently (with all the economic and ecological effects that this entails, e.g. through frequent arbitrary returns of goods, the delivery and shipping costs, parcel handling and ecological damage that comes along with this). -* 'Refund' from the seller's point of view: +* **Refund** from the seller's point of view: -As of today's implementation, in the event of a withdrawal from the purchase agreement, buyers bear the cost of the refund fee if the exchange charges it; in the event of a partial rebate, buyers bear the deposit fee for their used coins. Sellers are generally interested in keeping cancellations of contracts low and try to avoid unnecessary discount. +As of today's implementation, in the event of a withdrawal from the purchase agreement, buyers bear the cost of the 'Refund' fee if the exchange charges it; in the event of a partial rebate, buyers bear the deposit fee for their used coins. Sellers are generally interested in keeping cancellations of contracts low and try to avoid unnecessary discounting. +* **Wire fee** from the buyer's point of view: -* 'Wire fee' from the buyer's point of view: +This fee is to be paid by the sellers (i.e. merchants or generally all recipients of coins). The wire fee directly affects buyers only in the following case: The protocol allows sellers to partially pass on the cost of the wire fee to buyers if the Exchange operator that signed buyers' coins sets the wire fee above the value that each seller can define in the merchant backend via ``max_wire_fee``. It is no secret, though, that all the costs and the fees are included in retail price tags. At the end of the day, it is always the customers that pay. Nevertheless, sellers could pass on the relative cost advantages of the Taler payment system to their customers by offering lower retail prices, but they are not forced to do so. -This fee is to be paid by the sellers (i.e. merchants or generally all recipients of coins). The wire fee directly affects buyers only in the following case: The protocol allows sellers to partially pass on the cost of the wire fee to buyers if the Exchange operator that signed buyers' coins sets the wire fee above the value that each seller can define in the merchant backend via max_wire_fee. It is no secret, though, that all the costs and the fees are included in retail price tags. At the end of the day, it is always the customers to pay for. Nevertheless, sellers could pass on the relative cost advantages of the Taler payment system to their customers by offering lower retail prices, but they are not forced to do so. +* **Wire fee** from the Exchange operator's point of view: -* 'Wire fee' from the Exchange operator's point of view: +Exchange operators may charge wire fees in order to cover their expenses for wiring the value of coins to the beneficiaries. The wire fee passes on the cost of wire transfers from the Exchange's escrow account to the receiving banking accounts, and for this usually banks charge handling fees. Buyers are only shown the wire fee if the seller does not bear them to the full extent. For Exchange operators, opting out of the wire fee would be tantamount to giving sellers carte blanche to trigger an aggregated booking of their sales revenue as often as possible. If, on the other hand, the Exchange operator charges the wire fee, this will cause the sellers to adjust the frequency of the aggregated wire transfer as they need it for their business and want to afford the fee for it. As the frequency increases, so does the absolute cost due to wire fees to sellers. Buyers learn about the wire fee charge only in the event that an Exchange operator sets it higher than the value that a seller had defined with ``max_wire_fee``. -Exchange operators may charge wire fees in order to cover their expenses for wiring the value of coins to the beneficiaries. The wire fee passes on the cost of wire transfers from the Exchange's escrow account to the receiving banking accounts, and for this usually banks charge handling fees. Buyers are only shown the wire fee if the seller does not bear them to the full extent. For Exchange operators, opting out of the wire fee would be tantamount to giving sellers carte blanche to trigger an aggregated booking of their sales revenue as often as possible. If, on the other hand, the Exchange operator charges the wire fee, this will cause the sellers to adjust the frequency of the aggregated wire transfer as they need it for their business and want to afford the fee for it. As the frequency increases, so does the absolute cost due to wire fees to sellers. Buyers learn about the wire fee charge only in the event that an Exchange operator sets it higher than the value that a seller had defined with max_wire_fee. +* **Wire fee** from the seller's point of view: -* 'Wire fee' from the seller's point of view: +Sellers want to register their sales as quickly and often as possible. Timely revenue recognition improves their liquidity and generates interest income if sales revenues are received earlier than payments to suppliers. They are therefore forced to decide whether they would rather bear higher absolute costs due to the wire fee or forego liquidity. For some merchants, on the other hand, the volume of purchases determines the frequency of the aggregated wire transfer so as not to overload the accounting and billing departments. In any case, the costs of the wire fee are included in the buyer prices. -Sellers want to register their sales as quickly and often as possible. Timely revenue recognition improves their liquidity and generates interest income if sales revenues are received earlier than payments to suppliers. They are therefore forced to argue whether they would rather bear higher absolute costs due to the wire fee or forego liquidity. For some merchants, on the other hand, the volume of purchases determines the frequency of the aggregated wire transfer so as not to overload the accounting and billing departments. In any case, the costs of the wire fee are included in the end-user prices. +* **Closing** from the user's point of view: -* 'Closing' from the buyer's point of view: +The closing charge is triggered by users of the payment system if, after a successful wire transfer to an Exchange's escrow account, they do not have the reserve withdrawn to their personal wallet. This could be the case when for example the wallet did not connect to the Taler exchange within 14 days. Costs incur to the Exchange for the wire transfer back to the originating account. This is done by remitting the original amount minus the cost of wire transfers and possibly manual routing. The closing fee is easy to enforce and meets with understanding from most users. Commonly they will not be affected by this type of fee and can also quickly understand the Terms and conditions that they must bear the costs for self-inflicted issues at withdrawal. -The closing charge is triggered by users of the payment system if, after a successful wire transfer to an Exchange's escrow account, they do not have the reserve withdraw to their personal wallet. This could be the case when for example the wallet did not connect to the Taler exchange within 14 days. Costs incur to the Exchange for the wire transfer back to the originating account. This is done by remitting the original amount minus the cost of wire transfers and possibly manual routing. The closing fee is easy to enforce and meets with understanding from most users. Commonly they will not be affected by this type of fee and can also quickly understand the Terms and conditions that they must bear the costs for self-inflicted issues at withdrawal. - -* 'Closing' from the Exchange operator's point of view: +* **Closing** from the Exchange operator's point of view: Costs for the closing of a reserve are incurred by the Exchange operator due to irregular user behavior. However, Exchange operators may charge a fee for covering these costs to the user who caused them. The closing fee is indispensable for Exchange operators in order to prevent abuse through cost driving by malicious parties. Charging the fee by retaining it always works smoothly because the Exchange's escrow account is already in possession of users' funds through their wire transfers. -* 'Closing' from the seller's point of view: +* **Closing** from the seller's point of view: -The closing transaction does not affect sellers in any way. +The closing transaction does not affect sellers in any way. Alternatives ============ +Another way for Exchange operators to cover costs or generate income would be to set all of the above fees to zero and use income from the forfeiture of users' funds on the escrow account. Some voucher distributors even already use this income source as a normal business model. This solution might possibly be a "best case", since without confusing the users with a complex fee schedule and/or a range of fees. However, these revenues are discontinuous and unpredictable and therefore not really suitable for sustainable financing. + Drawbacks ========= -- cgit v1.2.3 From 5eec815a29c075ceeaf157c8dd8dbec11efa3e95 Mon Sep 17 00:00:00 2001 From: MS Date: Tue, 12 Jan 2021 18:50:11 +0100 Subject: nexus tells how many fresh-downloaded messages --- libeufin/api-nexus.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index 2d26a227..e32f3ce8 100644 --- a/libeufin/api-nexus.rst +++ b/libeufin/api-nexus.rst @@ -287,6 +287,15 @@ manages payment initiations of the account and tracks the initiations of payment bankConnection: string; } + **Response:** Tells how many new messages were downloaded from the bank, + in the following format: + + .. code-block:: ts + + interface NewMessages { + newMessages: number; + } + .. http:get:: {nexusBase}/bank-accounts/{acctid}/transactions Shows which transactions are stored locally at nexus. -- cgit v1.2.3 From 7fdb6a21a7c05e9b01c462919e25ec91f5651dfa Mon Sep 17 00:00:00 2001 From: MS Date: Tue, 12 Jan 2021 23:25:55 +0100 Subject: nexus tells general facades info --- libeufin/api-nexus.rst | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index e32f3ce8..12164f21 100644 --- a/libeufin/api-nexus.rst +++ b/libeufin/api-nexus.rst @@ -677,7 +677,24 @@ Facades .. http:get:: /facades - List available facades. + List available facades that belong to the requesting user. + + **Response:** + + .. code-block:: ts + + interface FacadeShowInfo { + + // Name of the facade, same as the "fcid" parameter. + name: string; + + // Type of the facade. + // For example, "taler-wire-gateway". + type: string; + + // Bas URL of the facade. + baseUrl: string; + } .. http:post:: {nexus}/facades -- cgit v1.2.3 From 2d65789ce244953169127b3853d8a8125c43dcb4 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 12 Jan 2021 22:25:36 -0500 Subject: taler-config-generate(1): don't mention GNUnet in ‘-v’ description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manpages/taler-config-generate.1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manpages/taler-config-generate.1.rst b/manpages/taler-config-generate.1.rst index 22f5c61f..a7c24e9a 100644 --- a/manpages/taler-config-generate.1.rst +++ b/manpages/taler-config-generate.1.rst @@ -88,7 +88,7 @@ for the Taler exchange or Taler merchants. ERROR. **-v** \| **––version** - Print GNUnet version number. + Print version information. Bugs ==== -- cgit v1.2.3 From b8830a42dd2bc3fece550b30709550b9df0dd3e9 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 12 Jan 2021 22:30:21 -0500 Subject: taler-config-generate(1): reorder opts in synopsis, description --- manpages/taler-config-generate.1.rst | 50 ++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/manpages/taler-config-generate.1.rst b/manpages/taler-config-generate.1.rst index a7c24e9a..5c9b813a 100644 --- a/manpages/taler-config-generate.1.rst +++ b/manpages/taler-config-generate.1.rst @@ -13,21 +13,21 @@ Synopsis ======== **taler-config-generate** -[**-c** *FILENAME* | **––config=**\ ‌\ *FILENAME*] [**-C** *CURRENCY* | **––currency=**\ ‌\ *CURRENCY*] +[**-c** *FILENAME* | **––config=**\ ‌\ *FILENAME*] [**-e** | **––exchange**] [**-f** *AMOUNT* | *––wirefee=*\ ‌\ *AMOUNT*] +[**-h** | **––help**] +[**-J** *JSON* | **––wire-json-exchange=**\ ‌\ *JSON*] +[**-j** *JSON* | **––wire-json-merchant=**\ ‌\ *JSON*] +[**-L** *LOGLEVEL* | **––loglevel=**\ ‌\ *LOGLEVEL*] [**-m** | **––merchant**] [**-t** | **––trusted**] +[**-v** | **––version**] [**-w** *WIREFORMAT* | **––wire** *WIREFORMAT*] -[**-j** *JSON* | **––wire-json-merchant=**\ ‌\ *JSON*] -[**-J** *JSON* | **––wire-json-exchange=**\ ‌\ *JSON*] [**––bank-uri**] [**––exchange-bank-account**] [**––merchant-bank-account**] -[**-h** | **––help**] -[**-L** *LOGLEVEL* | **––loglevel=**\ ‌\ *LOGLEVEL*] -[**-v** | **––version**] Description =========== @@ -35,13 +35,13 @@ Description **taler-config-generate** can be used to generate configuration files for the Taler exchange or Taler merchants. +**-C** *CURRENCY* \| **––currency=**\ ‌\ *CURRENCY* + Which currency should we use in the configuration. + **-c** *FILENAME* \| **––config=**\ ‌\ *FILENAME* Location where to write the generated configuration. Existing file will be updated, not overwritten. -**-C** *CURRENCY* \| **––currency=**\ ‌\ *CURRENCY* - Which currency should we use in the configuration. - **-e** \| **––exchange** Generate configuration for a Taler exchange. @@ -49,6 +49,19 @@ for the Taler exchange or Taler merchants. Setup wire transfer fees for the next 5 years for the exchange (for all wire methods). +**-h** \| **––help** + Shows this man page. + +**-J** *JSON* \| **––wire-json-exchange=**\ ‌\ *JSON* + Wire configuration to use for the exchange. + +**-j** *JSON* \| **––wire-json-merchant=**\ ‌\ *JSON* + Wire configuration to use for the merchant. + +**-L** *LOGLEVEL* \| **––loglevel=**\ ‌\ *LOGLEVEL* + Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and + ERROR. + **-m** \| **––merchant** Generate configuration for a Taler merchant. @@ -56,15 +69,12 @@ for the Taler exchange or Taler merchants. Setup current exchange as trusted with current merchant. Generally only useful when configuring for testcases. +**-v** \| **––version** + Print version information. + **-w** *WIREFORMAT* \| **––wire** *WIREFORMAT* Specifies which wire format to use (i.e. “test” or “sepa”) -**-j** *JSON* \| **––wire-json-merchant=**\ ‌\ *JSON* - Wire configuration to use for the merchant. - -**-J** *JSON* \| **––wire-json-exchange=**\ ‌\ *JSON* - Wire configuration to use for the exchange. - **––bank-uri** Alternative to specify wire configuration to use for the exchange and merchant for the “test” wire method. Only useful if WIREFORMAT was @@ -80,16 +90,6 @@ for the Taler exchange or Taler merchants. the “test” wire method. Only useful if WIREFORMAT was set to “test”. Specifies the bank account number of the merchant. -**-h** \| **––help** - Shows this man page. - -**-L** *LOGLEVEL* \| **––loglevel=**\ ‌\ *LOGLEVEL* - Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and - ERROR. - -**-v** \| **––version** - Print version information. - Bugs ==== -- cgit v1.2.3 From 7ed74e611b22a0f3ebaa35f55234f3780786933f Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 12 Jan 2021 23:28:18 -0500 Subject: taler-wallet-cli(1): reorder opts in synopsis, description --- manpages/taler-wallet-cli.1.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/manpages/taler-wallet-cli.1.rst b/manpages/taler-wallet-cli.1.rst index d109470b..8303fea1 100644 --- a/manpages/taler-wallet-cli.1.rst +++ b/manpages/taler-wallet-cli.1.rst @@ -13,8 +13,8 @@ Synopsis **taler-auditor** [**-h** | **––help**] -[**––verbose**] [**-V** | **––version**] +[**––verbose**] [] @@ -27,12 +27,12 @@ for testing. **-h** | **––help** Print short help on options. -**––verbose** - Enable verbose output. - **-V** | **––version** Output the version number. +**––verbose** + Enable verbose output. + **test-withdraw** [**-e** URL | **––exchange** URL] [**-a** AMOUNT | **––amount** AMOUNT][**-b** URL | **––bank** URL] withdraw test currency from the test bank -- cgit v1.2.3 From 695869d3c0f091173e25fb67e4a6c58edf564b97 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 12 Jan 2021 23:33:44 -0500 Subject: taler-merchant-benchmark(1): reorder opts in description --- manpages/taler-merchant-benchmark.1.rst | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/manpages/taler-merchant-benchmark.1.rst b/manpages/taler-merchant-benchmark.1.rst index 45f966dd..a314c994 100644 --- a/manpages/taler-merchant-benchmark.1.rst +++ b/manpages/taler-merchant-benchmark.1.rst @@ -65,15 +65,6 @@ corner Common Options ============== -**-k** *K* \| **––currency=**\ \ *K* - Use currency K, mandatory. - - -**-m** *URL* \| **––merchant-url=**\ \ *URL* - Use URL as the merchant base URL during the benchmark. The URL - is mainly used to download and pay for contracts. Mandatory. - - **-b** *URL* \| **––bank-url=**\ \ *URL* Use URL as the bank's base URL during the benchmark. The URL is used to test whether the bank is up and running. Mandatory. @@ -85,14 +76,21 @@ Common Options **-h** \| **––help** Print short help on options. -**-v** \| **––version** - Print version information. +**-k** *K* \| **––currency=**\ \ *K* + Use currency K, mandatory. + +**-L** *LOGLEVEL* \| **––log=**\ \ *LOGLEVEL* + Use loglevel LOGLEVEL. **-l** *LF* \| **––logfile=**\ \ *LF* Sends logs to file whose path is LF. -**-L** *LOGLEVEL* \| **––log=**\ \ *LOGLEVEL* - Use loglevel LOGLEVEL. +**-m** *URL* \| **––merchant-url=**\ \ *URL* + Use URL as the merchant base URL during the benchmark. The URL + is mainly used to download and pay for contracts. Mandatory. + +**-v** \| **––version** + Print version information. See Also -- cgit v1.2.3 From 1f4b812bd7ea8b452e1c72c5e26f2201229314b3 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 12 Jan 2021 23:34:34 -0500 Subject: taler-merchant-benchmark(1): rewrite descriptions for ‘-L’, ‘-l’ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manpages/taler-merchant-benchmark.1.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/manpages/taler-merchant-benchmark.1.rst b/manpages/taler-merchant-benchmark.1.rst index a314c994..1868cac3 100644 --- a/manpages/taler-merchant-benchmark.1.rst +++ b/manpages/taler-merchant-benchmark.1.rst @@ -79,11 +79,12 @@ Common Options **-k** *K* \| **––currency=**\ \ *K* Use currency K, mandatory. -**-L** *LOGLEVEL* \| **––log=**\ \ *LOGLEVEL* - Use loglevel LOGLEVEL. +**-L** *LOGLEVEL* \| **––loglevel=**\ ‌\ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. -**-l** *LF* \| **––logfile=**\ \ *LF* - Sends logs to file whose path is LF. +**-l** *FILENAME* \| **––logfile=**\ ‌\ *FILENAME* + Send logging output to *FILENAME*. **-m** *URL* \| **––merchant-url=**\ \ *URL* Use URL as the merchant base URL during the benchmark. The URL -- cgit v1.2.3 From bca2a39520f9d91038fd6516a62caeb23c331ec0 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 12 Jan 2021 23:35:24 -0500 Subject: dedent (nine instances) --- manpages/taler-merchant-benchmark.1.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/manpages/taler-merchant-benchmark.1.rst b/manpages/taler-merchant-benchmark.1.rst index 1868cac3..651c64d1 100644 --- a/manpages/taler-merchant-benchmark.1.rst +++ b/manpages/taler-merchant-benchmark.1.rst @@ -66,18 +66,18 @@ Common Options ============== **-b** *URL* \| **––bank-url=**\ \ *URL* - Use URL as the bank's base URL during the benchmark. The URL is - used to test whether the bank is up and running. Mandatory. + Use URL as the bank's base URL during the benchmark. The URL is + used to test whether the bank is up and running. Mandatory. **-c** *FILENAME* \| **––config=**\ \ *FILENAME* - Use the configuration and other resources for the merchant to - operate from FILENAME. + Use the configuration and other resources for the merchant to + operate from FILENAME. **-h** \| **––help** - Print short help on options. + Print short help on options. **-k** *K* \| **––currency=**\ \ *K* - Use currency K, mandatory. + Use currency K, mandatory. **-L** *LOGLEVEL* \| **––loglevel=**\ ‌\ *LOGLEVEL* Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, @@ -87,11 +87,11 @@ Common Options Send logging output to *FILENAME*. **-m** *URL* \| **––merchant-url=**\ \ *URL* - Use URL as the merchant base URL during the benchmark. The URL - is mainly used to download and pay for contracts. Mandatory. + Use URL as the merchant base URL during the benchmark. The URL + is mainly used to download and pay for contracts. Mandatory. **-v** \| **––version** - Print version information. + Print version information. See Also -- cgit v1.2.3 From 0771c6745d609f7fc0e6d7221020ba04d2fc2844 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 12 Jan 2021 23:51:36 -0500 Subject: taler-merchant-benchmark(1): add opt ‘-a’ to Common Options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manpages/taler-merchant-benchmark.1.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/manpages/taler-merchant-benchmark.1.rst b/manpages/taler-merchant-benchmark.1.rst index 651c64d1..75fdb2f3 100644 --- a/manpages/taler-merchant-benchmark.1.rst +++ b/manpages/taler-merchant-benchmark.1.rst @@ -65,6 +65,9 @@ corner Common Options ============== +**-a** *APIKEY* \| **--apikey=**\ \ *APIKEY* + HTTP 'Authorization' header to send to the merchant. + **-b** *URL* \| **––bank-url=**\ \ *URL* Use URL as the bank's base URL during the benchmark. The URL is used to test whether the bank is up and running. Mandatory. -- cgit v1.2.3 From cd09fb958f0d6965be66d842362b56db6cb87e27 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 12 Jan 2021 23:53:33 -0500 Subject: taler-merchant-benchmark(1): add opt ‘-e’ to Common Options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manpages/taler-merchant-benchmark.1.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/manpages/taler-merchant-benchmark.1.rst b/manpages/taler-merchant-benchmark.1.rst index 75fdb2f3..fc14d22b 100644 --- a/manpages/taler-merchant-benchmark.1.rst +++ b/manpages/taler-merchant-benchmark.1.rst @@ -76,6 +76,10 @@ Common Options Use the configuration and other resources for the merchant to operate from FILENAME. +**-e** *SECTION* \| **--exchange-account=**\ \ *SECTION* + Mandatory. + Configuration *SECTION* specifying the exchange account to use. + **-h** \| **––help** Print short help on options. -- cgit v1.2.3 From f9465861a61e319ed01ed412424e908dfd478a38 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 12 Jan 2021 23:56:14 -0500 Subject: taler-merchant-benchmark(1): delete opt ‘-i’ from ‘corner’ options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manpages/taler-merchant-benchmark.1.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/manpages/taler-merchant-benchmark.1.rst b/manpages/taler-merchant-benchmark.1.rst index fc14d22b..4034a0e2 100644 --- a/manpages/taler-merchant-benchmark.1.rst +++ b/manpages/taler-merchant-benchmark.1.rst @@ -50,11 +50,6 @@ corner payments use only one coin). TC defaults to 1. - **-i** *AI* \| **––alt-instance=**\ \ *AI* - Use AI as the instance, instead of 'default' (which is the - default instance used.) - - **-u** *UN* \| **––unaggregated-number=**\ \ *UN* Generate UN payments that will be left unaggregated. Note that subsequent invocations of the generator may pick those -- cgit v1.2.3 From 1c79852fa63861c2b368889a35a60f36e69139d7 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Tue, 12 Jan 2021 23:57:54 -0500 Subject: taler-merchant-benchmark(1): delete opts ‘-b’, ‘-k’, ‘-m’ from "Common Options" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- manpages/taler-merchant-benchmark.1.rst | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/manpages/taler-merchant-benchmark.1.rst b/manpages/taler-merchant-benchmark.1.rst index 4034a0e2..a8af27a0 100644 --- a/manpages/taler-merchant-benchmark.1.rst +++ b/manpages/taler-merchant-benchmark.1.rst @@ -63,10 +63,6 @@ Common Options **-a** *APIKEY* \| **--apikey=**\ \ *APIKEY* HTTP 'Authorization' header to send to the merchant. -**-b** *URL* \| **––bank-url=**\ \ *URL* - Use URL as the bank's base URL during the benchmark. The URL is - used to test whether the bank is up and running. Mandatory. - **-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the merchant to operate from FILENAME. @@ -78,9 +74,6 @@ Common Options **-h** \| **––help** Print short help on options. -**-k** *K* \| **––currency=**\ \ *K* - Use currency K, mandatory. - **-L** *LOGLEVEL* \| **––loglevel=**\ ‌\ *LOGLEVEL* Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``. @@ -88,10 +81,6 @@ Common Options **-l** *FILENAME* \| **––logfile=**\ ‌\ *FILENAME* Send logging output to *FILENAME*. -**-m** *URL* \| **––merchant-url=**\ \ *URL* - Use URL as the merchant base URL during the benchmark. The URL - is mainly used to download and pay for contracts. Mandatory. - **-v** \| **––version** Print version information. -- cgit v1.2.3 From 263037c68a87dac8d208487ca338be7283aa294f Mon Sep 17 00:00:00 2001 From: MS Date: Wed, 13 Jan 2021 10:48:18 +0100 Subject: completing type description --- libeufin/api-nexus.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index 12164f21..64fc48e5 100644 --- a/libeufin/api-nexus.rst +++ b/libeufin/api-nexus.rst @@ -679,7 +679,7 @@ Facades List available facades that belong to the requesting user. - **Response:** + **Response:** A list of the following elements: .. code-block:: ts -- cgit v1.2.3 From c1f3909466600345488557e2cee9ac638a4a2a31 Mon Sep 17 00:00:00 2001 From: MS Date: Wed, 13 Jan 2021 11:01:24 +0100 Subject: use Any on unknown types --- libeufin/api-nexus.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index 64fc48e5..0fd08743 100644 --- a/libeufin/api-nexus.rst +++ b/libeufin/api-nexus.rst @@ -675,13 +675,18 @@ to the real bank. Facades ------- +.. http:get:: /facades/{fcid} + + **Response:** A `FacadeShowInfo` pointed to by ``fcid``. + + .. http:get:: /facades List available facades that belong to the requesting user. **Response:** A list of the following elements: - .. code-block:: ts +.. ts:def:: FacadeShowInfo interface FacadeShowInfo { @@ -694,17 +699,18 @@ Facades // Bas URL of the facade. baseUrl: string; + + // details depending on the facade type. + config: any; } .. http:post:: {nexus}/facades - Create a new facade; it requires a `FacadeInfo` as the request's body. - -.. http:get:: {nexus}/facades/${fcid} + Create a new facade. - Get details about a facade. + **Request:** - .. ts:def:: FacadeInfo + .. code-block:: ts interface FacadeInfo { // Name of the facade, same as the "fcid" parameter. -- cgit v1.2.3 From 82dcb7c6566242da99695d4272b995b4cdfec141 Mon Sep 17 00:00:00 2001 From: Stefan Kügel Date: Wed, 13 Jan 2021 15:10:38 +0100 Subject: Added internal links in the doc, applied markup --- design-documents/012-fee-schedule-metrics.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/design-documents/012-fee-schedule-metrics.rst b/design-documents/012-fee-schedule-metrics.rst index 612393d7..6e6afb61 100644 --- a/design-documents/012-fee-schedule-metrics.rst +++ b/design-documents/012-fee-schedule-metrics.rst @@ -24,16 +24,16 @@ Proposed Solution The Taler protocol offers the following fee types: -1. **Withdrawal**: For each successful withdrawal from the checking account, per coin -2. **Deposit**: For spending, per coin -3. **Refresh**: Per coin for +1. **Withdrawal**: For each successful withdrawal from the checking account, **per coin** +2. **Deposit**: For spending, **per coin** +3. **Refresh**: **Per coin** for a. Refresh transactions for receiving change b. Refresh of coins at the end of their validity c. Abort of transactions due to network failure d. Refund 4. **Refund**: For refunds or in case of contract cancellation by seller, per coin -5. **Wire fee**: For aggregated amounts wired by the Exchange to the merchant's checking account, per wire transfer -6. **Closing**: In case a withdrawal process could not be accomplished (the user's wallet did not withdraw the value from the reserve), per wire transfer from the Exchange's escrow account to the account of origin +5. **Wire fee**: For aggregated amounts wired by the Exchange to the merchant's checking account, **per wire transfer** +6. **Closing**: In case a withdrawal process could not be accomplished (the user's wallet did not withdraw the value from the reserve), **per wire transfer** from the Exchange's escrow account to the account of origin Fee schedule ============ @@ -104,7 +104,7 @@ Anyone who wants to load Taler wallets with coins must initiate a wire transfer * **Withdrawal** from the Exchange operator's point of view: -A fee on each coin generated would indeed affect all electronic coins withdrawn from an exchange operator and allocate costs necessary for their generation over all coins signed for the first time, but would not prevent abuse through other transactions like intentionally often-triggered refresh or refund, and would also discriminate against those users who withdraw and deposit many smaller denominations. Furthermore, buyers using coins with higher denominations could increase the exchange operator's costs by increasing refresh transactions. Overall, the cost increases are marginally small, though. +A fee on each coin generated would indeed affect all electronic coins withdrawn from an Exchange operator and allocate costs necessary for their generation over all coins signed for the first time, but would not prevent abuse through other transactions like intentionally often-triggered refresh or refund, and would also discriminate against those users who withdraw and deposit many smaller denominations. Furthermore, buyers using coins with higher denominations could increase the Exchange operator's costs by increasing refresh transactions. Overall, the cost increases are marginally small, though. * **Withdrawal** from the seller's point of view: @@ -188,3 +188,7 @@ Drawbacks Discussion / Q&A ================ + +We should insert pointers to other design documents regarding fee specifications in our documentation: +:doc:`008-fees` + -- cgit v1.2.3 From 96b81f6089bdcc330fbfb52336a8d6e828455761 Mon Sep 17 00:00:00 2001 From: Stefan Kügel Date: Wed, 13 Jan 2021 15:19:04 +0100 Subject: Applied markup definition to the last paragraph --- design-documents/008-fees.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/design-documents/008-fees.rst b/design-documents/008-fees.rst index a3d5ca6a..88770ac3 100644 --- a/design-documents/008-fees.rst +++ b/design-documents/008-fees.rst @@ -120,13 +120,13 @@ Discussion / Q&A ================ The Taler protocol offers the following fee types: -1. 'Withdrawal': For each successful withdrawal from the checking account, per coin -2. 'Deposit': For spending, per coin -3. 'Refresh': Per coin for +1. **Withdrawal**: For each successful withdrawal from the checking account, **per coin** +2. **Deposit**: For spending, **per coin** +3. **Refresh**: **Per coin** for a. Refresh transactions for receiving change b. Refresh of coins at the end of their validity c. Abort of transactions due to network failure d. Refund -4. 'Refund': For refunds or in case of contract cancellation by seller, per coin -5. 'Wire fee': For aggregated amounts wired by the Exchange to the merchant's checking account, per wired transfer -6. 'Closing': In case that a withdrawal process could not be accomplished (the users' wallet did not withdraw the value from the reserve), per wired transfer from the Exchange's escrow account to the account of origin +4. **Refund**: For refunds or in case of contract cancellation by seller, per coin +5. **Wire fee**: For aggregated amounts wired by the Exchange to the merchant's checking account, **per wire transfer** +6. **Closing**: In case a withdrawal process could not be accomplished (the user's wallet did not withdraw the value from the reserve), **per wire transfer** from the Exchange's escrow account to the account of origin -- cgit v1.2.3