rfqmath: add AddTolerance helper

Author: GeorgeTsagk

rfqmath/fixed_point.go

@@ -186,6 +186,23 @@ func (f FixedPoint[T]) WithinTolerance(
 	return result, nil
 }
 
+// AddTolerance applies the given tolerance expressed in parts per million (ppm)
+// to the provided amount.
+func AddTolerance(value, tolerancePpm BigInt) BigInt {
+	// A placeholder variable for ppm value denominator (1 million).
+	ppmBase := NewBigIntFromUint64(1_000_000)
+
+	// Convert the tolerancePpm value to the actual units that express this
+	// margin.
+	toleranceUnits := value.Mul(tolerancePpm).Div(ppmBase)
+
+	res := value.Add(toleranceUnits)
+
+	// We now add the tolerance margin to the original value and return the
+	// result.
+	return res
+}
+
 // FixedPointFromUint64 creates a new FixedPoint from the given integer and
 // scale. Note that the input here should be *unscaled*.
 func FixedPointFromUint64[N Int[N]](value uint64, scale uint8) FixedPoint[N] {

rfqmath/fixed_point_test.go

@@ -396,6 +396,44 @@ func testWithinToleranceZeroTolerance(t *rapid.T) {
 	require.True(t, result)
 }
 
+// testAddToleranceProp is a property-based test which tests that the
+// AddTolerance helper correctly applies the provided tolerance margin to any
+// given value.
+func testAddToleranceProp(t *rapid.T) {
+	value := NewBigIntFromUint64(rapid.Uint64Min(1).Draw(t, "value"))
+	tolerancePpm := NewBigIntFromUint64(
+		rapid.Uint64Range(0, 1_000_000).Draw(t, "tolerance_ppm"),
+	)
+
+	result := AddTolerance(value, tolerancePpm)
+
+	if tolerancePpm.ToUint64() == 0 {
+		require.True(t, result.Equals(value))
+		return
+	}
+
+	// First off, let's just check that the result is at all greater than
+	// the input.
+	require.True(t, result.Gte(value))
+
+	// Let's now convert the values to a fixed point type in order to use
+	// the WithinTolerance method.
+	valueFixed := BigIntFixedPoint{
+		Coefficient: value,
+		Scale:       0,
+	}
+	resultFixed := BigIntFixedPoint{
+		Coefficient: result,
+		Scale:       0,
+	}
+
+	// The value with the applied tolerance and the original value should be
+	// within tolerance.
+	res, err := resultFixed.WithinTolerance(valueFixed, tolerancePpm)
+	require.NoError(t, err)
+	require.True(t, res)
+}
+
 // testWithinToleranceSymmetric is a property-based test which ensures that the
 // WithinTolerance method is symmetric (swapping the order of the fixed-point
 // values does not change the result).
@@ -600,6 +638,11 @@ func testWithinTolerance(t *testing.T) {
 		"within_tolerance_float_reproduce",
 		rapid.MakeCheck(testWithinToleranceFloatReproduce),
 	)
+
+	t.Run(
+		"add_tolerance_property",
+		rapid.MakeCheck(testAddToleranceProp),
+	)
 }
 
 // TestFixedPoint runs a series of property-based tests on the FixedPoint type