feat: basis points math package

util/bpmath/bp.go

@@ -0,0 +1,49 @@
+package bpmath
+
+import (
+	"math"
+
+	cmath "cosmossdk.io/math"
+)
+
+// BP represents values in basis points. Maximum value is 2^32-1.
+// Note: BP operations should not be chained - this causes precision loses.
+type BP uint32
+
+// FromQuo returns a/b in basis points.
+// Contract: a>=0 and b > 0.
+// Panics if a/b >= MaxUint32/10'000 or if b==0.
+func FromQuo(dividend, divisor cmath.Int, rounding Rounding) BP {
+	return BP(quo(dividend, divisor, rounding, math.MaxUint32))
+}
+
+func quo(a, b cmath.Int, rounding Rounding, max uint64) uint64 {
+	if b.IsZero() {
+		panic("divider can't be zero")
+	}
+	bp := a.MulRaw(ONE)
+	if rounding == UP {
+		bp = bp.Add(b.SubRaw(1))
+	}
+	x := bp.Quo(b).Uint64()
+	if x > max {
+		panic("basis points out of band")
+	}
+	return x
+}
+
+// Mul returns a * b_basis_points
+// Contract: b \in [0; MatxUint32]
+func Mul[T BP | FixedBP](a cmath.Int, b T) cmath.Int {
+	if b == 0 {
+		return cmath.ZeroInt()
+	}
+	if b == ONE {
+		return a
+	}
+	return a.MulRaw(int64(b)).Quo(oneBigInt)
+}
+
+func (bp BP) ToDec() cmath.LegacyDec {
+	return cmath.LegacyNewDecWithPrec(int64(bp), 4)
+}

util/bpmath/bp_test.go

@@ -0,0 +1,26 @@
+package bpmath
+
+import (
+	"fmt"
+	"testing"
+
+	"cosmossdk.io/math"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBPToDec(t *testing.T) {
+	t.Parallel()
+	tcs := []struct {
+		name string
+		a    FixedBP
+		exp  math.LegacyDec
+	}{
+		{"t1", 99999, math.LegacyMustNewDecFromStr("9.9999")},
+		{"t2", ONE * 10, math.LegacyMustNewDecFromStr("10.0")},
+	}
+	require := require.New(t)
+	for _, tc := range tcs {
+		bp := BP(tc.a).ToDec()
+		require.Equal(tc.exp.String(), bp.String(), fmt.Sprint("test-bp ", tc.name))
+	}
+}

util/bpmath/doc.go

@@ -0,0 +1,4 @@
+// Package bpmath provides types and functions for doing basis point operations.
+// There is no precision lost for operations like `a * b` where `a` or `b` is basis points,
+// and the other variable is `Int`.
+package bpmath

util/bpmath/fixed_bp.go

@@ -0,0 +1,20 @@
+package bpmath
+
+import (
+	"cosmossdk.io/math"
+)
+
+// FixedBP assures that all oprations are in 0-10'000 range
+// Note: FixedBP operations should not be chained - this causes precision loses.
+type FixedBP uint32
+
+// FixedFromQuo returns a/b in basis points. Returns 10'000 if a >= b;
+// Contract: a>=0 and b > 0.
+// Panics if b==0.
+func FixedFromQuo(dividend, divisor math.Int, rounding Rounding) FixedBP {
+	return FixedBP(quo(dividend, divisor, rounding, ONE))
+}
+
+func (bp FixedBP) ToDec() math.LegacyDec {
+	return math.LegacyNewDecWithPrec(int64(bp), 4)
+}

util/bpmath/fixed_bp_test.go

@@ -0,0 +1,109 @@
+package bpmath
+
+import (
+	"fmt"
+	"testing"
+
+	"cosmossdk.io/math"
+	"github.com/stretchr/testify/require"
+)
+
+func TestFixedQuo(t *testing.T) {
+	t.Parallel()
+	tcs := []struct {
+		name   string
+		a      uint64
+		b      uint64
+		r      Rounding
+		exp    FixedBP
+		panics bool
+	}{
+		{"t1", 0, 0, UP, ONE, true},
+		{"t2", 0, 0, DOWN, ONE, true},
+		{"t3", 1, 0, UP, ONE, true},
+		{"t4", 1, 0, DOWN, ONE, true},
+
+		{"t5", 20, 10, UP, 0, true},
+		{"t6", 20, 10, DOWN, 0, true},
+		{"t7", 20, 20, UP, ONE, false},
+		{"t7-1", 20, 20, DOWN, ONE, false},
+
+		{"t8", 1, 2, UP, ONE / 2, false},
+		{"t9", 1, 2, DOWN, ONE / 2, false},
+		{"t10", 1, 3, UP, 3334, false},
+		{"t11", 1, 3, DOWN, 3333, false},
+		{"t12", 2, 3, UP, 6667, false},
+		{"t13", 2, 3, DOWN, 6666, false},
+		{"t14", 10, 99999, UP, 2, false},
+		{"t15", 10, 99999, DOWN, 1, false},
+		{"t16", 10, 99999999, UP, 1, false},
+		{"t17", 10, 99999999, DOWN, 0, false},
+	}
+	require := require.New(t)
+	for _, tc := range tcs {
+		a, b := math.NewIntFromUint64(tc.a), math.NewIntFromUint64(tc.b)
+		if tc.panics {
+			require.Panics(func() {
+				FixedFromQuo(a, b, tc.r)
+			}, tc.name)
+			continue
+		}
+		o := FixedFromQuo(a, b, tc.r)
+		require.Equal(int(tc.exp), int(o), fmt.Sprint("test ", tc.name))
+	}
+}
+
+func TestFixedMul(t *testing.T) {
+	t.Parallel()
+	tcs := []struct {
+		name string
+		a    uint64
+		b    BP
+		exp  uint64
+	}{
+		{"t1", 20, 0, 0},
+		{"t2", 20, 1, 0},
+		{"t3", 20, ONE, 20},
+		{"t4", 20000, 0, 0},
+		{"t5", 20000, 1, 2},
+		{"t6", 20000, 2, 4},
+		{"t7", 20000, half, 10000},
+		{"t8", 2000, 4, 0},
+		{"t9", 2000, 5, 1},
+		{"t10", 2000, half, 1000},
+	}
+	require := require.New(t)
+	for _, tc := range tcs {
+		a := math.NewIntFromUint64(tc.a)
+		o := Mul(a, tc.b)
+		require.Equal(int64(tc.exp), o.Int64(), fmt.Sprint("test ", tc.name))
+
+		// must work with both FixedBP and BP
+		o = Mul(a, FixedBP(tc.b))
+		require.Equal(int64(tc.exp), o.Int64(), fmt.Sprint("test ", tc.name))
+
+	}
+}
+
+func TestFixedToDec(t *testing.T) {
+	t.Parallel()
+	tcs := []struct {
+		name string
+		a    FixedBP
+		exp  math.LegacyDec
+	}{
+		{"t1", 0, math.LegacyZeroDec()},
+		{"t2", 1, math.LegacyMustNewDecFromStr("0.0001")},
+		{"t3", 20, math.LegacyMustNewDecFromStr("0.002")},
+		{"t4", 9999, math.LegacyMustNewDecFromStr("0.9999")},
+		{"t5", ONE, math.LegacyNewDec(1)},
+	}
+	require := require.New(t)
+	for _, tc := range tcs {
+		o := tc.a.ToDec()
+		require.Equal(tc.exp.String(), o.String(), fmt.Sprint("test-fixedbp ", tc.name))
+
+		bp := BP(tc.a).ToDec()
+		require.Equal(tc.exp.String(), bp.String(), fmt.Sprint("test-bp ", tc.name))
+	}
+}

util/bpmath/types.go

@@ -0,0 +1,19 @@
+package bpmath
+
+import (
+	"cosmossdk.io/math"
+)
+
+type Rounding uint
+
+const (
+	DOWN = iota
+	UP
+)
+
+const ONE = 10000
+const half = ONE / 2
+
+var (
+	oneBigInt = math.NewIntFromUint64(ONE)
+)