commit cd7fc3edac1cd138ed52bd92fe19a46283f352a5
parent 33e39e427cc90aab28354f452f356c1e0b355fcf
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 24 Aug 2023 21:07:06 +0200
update DD47
Diffstat:
1 file changed, 32 insertions(+), 7 deletions(-)
diff --git 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
