[taler-docs] branch master updated: update DD47

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new cd7fc3ed update DD47
cd7fc3ed is described below

commit cd7fc3edac1cd138ed52bd92fe19a46283f352a5
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Thu Aug 24 21:07:06 2023 +0200

    update DD47
---
 design-documents/047-stefan.rst | 39 ++++++++++++++++++++++++++++++++-------
 1 file changed, 32 insertions(+), 7 deletions(-)

diff --git a/design-documents/047-stefan.rst b/design-documents/047-stefan.rst
index 8ae3586e..47d97725 100644
--- a/design-documents/047-stefan.rst
+++ b/design-documents/047-stefan.rst
@@ -38,14 +38,39 @@ Proposed Solution
 
 The proposal is for the exchange to advertise three STEFAN-parameters that
 encode a fee curve of the form ``stefan_abs + stefan_log * log P +
-stefan_lin * P`` where P represents the price to be paid.
+stefan_lin * P`` where P represents the gross price to be paid.
 Here, the numerical value for P is to be computed by
-dividing the actual price by the smallest denomination
-offered by the exchange. The fee curve will be the
-displayed fee, except in cases where the coin selection is exceptionally bad
-(which should happen in substantially less than 1% of all cases).  The fee
-curve will also be used as the maximum fee a merchant will cover unless the
-merchant overrides the mechanism.
+dividing the actual gross price by the smallest denomination
+offered by the exchange.
+
+.. note::
+
+   This calculation is already done using floating point (!) as we want the
+   STEFAN-curve to be smooth and not a step-function. This is also needed so
+   that we can invert the computation and calculate gross amounts from net
+   amounts and actually get a nice invertible computation where both
+   directions always match.  Note that the computation itself is nevertheless
+   non-trivial involving Newton's method to solve `f(x)=0` using a
+   well-estimated starting point for the iteration to avoid divergence issues.
+   Finally, while we do the STEFAN-curve computations using doubles, we should
+   then convert the final amounts back into "human-friendly" numbers rounding
+   towards the nearest value that can be represented using the canonical
+   number of decimal places at the exchange.  libtalerexchange (C) has a
+   reference implementation of the gross-net conversion functions (in both
+   directions) and of the final rounding logic.  This exception to the general
+   rule of no floating-points for amounts is acceptable as it is not actually
+   done at the protocol level but only in internal computations of the wallet
+   and merchant backend as part of the STEFAN cost estimation logic, which by
+   definition is an estimate and does not need to be exact.  (And even if
+   wallet and merchant backend were to (slightly) disagree about the
+   computations due to different floating point implementations, everything
+   would still be fine, and even a significant disagreement would not cause
+   anything but resurface the UI issue the STEFAN-curves addresses.)
+
+The fee curve will be the displayed fee, except in cases where the coin
+selection is exceptionally bad (which should happen in substantially less than
+1% of all cases).  The fee curve will also be used as the maximum fee a
+merchant will cover unless the merchant overrides the mechanism.
 
 In the most common case, where the STEFAN-curve fee is at or below what the
 merchant covers, no fees are displayed, except in the exceptionally rare

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