test(common): add docs for testutil and increase test coverage

CHANGELOG.md

@@ -55,6 +55,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * [#1520](https://github.com/NibiruChain/nibiru/pull/1520) - feat(wasm): no op handler + tests with updated contracts
 * [#1521](https://github.com/NibiruChain/nibiru/pull/1521) - test(sudo): increase unit test coverage
 * [#1523](https://github.com/NibiruChain/nibiru/pull/1523) - chore: bump cosmos-sdk to v0.47.4
+* [#1527](https://github.com/NibiruChain/nibiru/pull/1527) - test(common): add docs for testutil and increase test coverage
 * [#1536](https://github.com/NibiruChain/nibiru/pull/1536) - test(perp): add more tests to perp module and cli
 * [#1533](https://github.com/NibiruChain/nibiru/pull/1533) - feat(perp): add differential fields to PositionChangedEvent
 
@@ -633,4 +634,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Testing
 
 * [#695](https://github.com/NibiruChain/nibiru/pull/695) Add `OpenPosition` integration tests.
-* [#692](https://github.com/NibiruChain/nibiru/pull/692) Add test coverage for Perp MsgServer methods.
+* [#692](https://github.com/NibiruChain/nibiru/pull/692) Add test coverage for Perp MsgServer methods.

x/common/address_test.go

@@ -0,0 +1,19 @@
+package common_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/NibiruChain/nibiru/x/common"
+	"github.com/NibiruChain/nibiru/x/common/testutil"
+)
+
+func TestAddress(t *testing.T) {
+	require.NotPanics(t, func() {
+		_, addrs := testutil.PrivKeyAddressPairs(5)
+		strs := common.AddrsToStrings(addrs...)
+		addrsOut := common.StringsToAddrs(strs...)
+		require.EqualValues(t, addrs, addrsOut)
+	})
+}

x/common/asset/pair.go

@@ -149,49 +149,19 @@ func (pairKeyEncoder) Decode(b []byte) (int, Pair) {
 	return i, MustNewPair(s)
 }
 
-//-----------------------------------------------------------------------------
-// Pairs
-
-// Pairs is a set of Pair, one per pair.
-type Pairs []Pair
-
-// News constructs a new asset pair set. A panic will occur if one of
+// MustNewPairs constructs a new asset pair set. A panic will occur if one of
 // the provided pair names is invalid.
-func News(pairStrings ...string) (pairs Pairs) {
+func MustNewPairs(pairStrings ...string) (pairs []Pair) {
 	for _, pairString := range pairStrings {
 		pairs = append(pairs, MustNewPair(pairString))
 	}
 	return pairs
 }
 
-// Contains checks if a token pair is contained within 'Pairs'
-func (haystack Pairs) Contains(needle Pair) bool {
-	for _, p := range haystack {
-		if p.Equal(needle) {
-			return true
-		}
-	}
-	return false
-}
-
-func (pairs Pairs) Strings() []string {
+func PairsToStrings(pairs []Pair) []string {
 	pairsStrings := []string{}
 	for _, pair := range pairs {
 		pairsStrings = append(pairsStrings, pair.String())
 	}
 	return pairsStrings
 }
-
-func (pairs Pairs) Validate() error {
-	seenPairs := make(map[string]bool)
-	for _, pair := range pairs {
-		if seenPairs[pair.String()] {
-			return fmt.Errorf("duplicate pair %s", pair.String())
-		}
-		if err := pair.Validate(); err != nil {
-			return err
-		}
-		seenPairs[pair.String()] = true
-	}
-	return nil
-}

x/common/asset/pair_test.go

@@ -1,11 +1,14 @@
-package asset
+package asset_test
 
 import (
 	"fmt"
 	"testing"
 
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	"github.com/NibiruChain/nibiru/app/codec"
+	"github.com/NibiruChain/nibiru/x/common/asset"
 	"github.com/NibiruChain/nibiru/x/common/denoms"
 )
 
@@ -20,17 +23,17 @@ func TestTryNewPair(t *testing.T) {
 		{
 			"only one token",
 			denoms.NIBI,
-			ErrInvalidTokenPair,
+			asset.ErrInvalidTokenPair,
 		},
 		{
 			"more than 2 tokens",
 			fmt.Sprintf("%s:%s:%s", denoms.NIBI, denoms.NUSD, denoms.USDC),
-			ErrInvalidTokenPair,
+			asset.ErrInvalidTokenPair,
 		},
 		{
 			"different separator",
 			fmt.Sprintf("%s,%s", denoms.NIBI, denoms.NUSD),
-			ErrInvalidTokenPair,
+			asset.ErrInvalidTokenPair,
 		},
 		{
 			"correct pair",
@@ -57,7 +60,7 @@ func TestTryNewPair(t *testing.T) {
 	for _, tc := range tests {
 		tc := tc
 		t.Run(tc.name, func(t *testing.T) {
-			_, err := TryNewPair(tc.tokenStr)
+			_, err := asset.TryNewPair(tc.tokenStr)
 			if tc.err != nil {
 				require.ErrorContains(t, err, tc.err.Error())
 			} else {
@@ -68,17 +71,17 @@ func TestTryNewPair(t *testing.T) {
 }
 
 func TestGetDenoms(t *testing.T) {
-	pair := MustNewPair("uatom:unibi")
+	pair := asset.MustNewPair("uatom:unibi")
 
 	require.Equal(t, "uatom", pair.BaseDenom())
 	require.Equal(t, "unibi", pair.QuoteDenom())
 }
 
 func TestEquals(t *testing.T) {
-	pair := MustNewPair("abc:xyz")
-	matchingOther := MustNewPair("abc:xyz")
-	mismatchToken1 := MustNewPair("abc:abc")
-	inversePair := MustNewPair("xyz:abc")
+	pair := asset.MustNewPair("abc:xyz")
+	matchingOther := asset.MustNewPair("abc:xyz")
+	mismatchToken1 := asset.MustNewPair("abc:abc")
+	inversePair := asset.MustNewPair("xyz:abc")
 
 	require.True(t, pair.Equal(matchingOther))
 	require.False(t, pair.Equal(inversePair))
@@ -87,17 +90,91 @@ func TestEquals(t *testing.T) {
 
 func TestMustNewAssetPair(t *testing.T) {
 	require.Panics(t, func() {
-		MustNewPair("aaa:bbb:ccc")
+		asset.MustNewPair("aaa:bbb:ccc")
 	})
 
 	require.NotPanics(t, func() {
-		MustNewPair("aaa:bbb")
+		asset.MustNewPair("aaa:bbb")
 	})
 }
 
 func TestInverse(t *testing.T) {
-	pair := MustNewPair("abc:xyz")
+	pair := asset.MustNewPair("abc:xyz")
 	inverse := pair.Inverse()
 	require.Equal(t, "xyz", inverse.BaseDenom())
 	require.Equal(t, "abc", inverse.QuoteDenom())
 }
+
+func TestMarshalJSON(t *testing.T) {
+	cdc := codec.MakeEncodingConfig()
+
+	testCases := []struct {
+		name      string
+		input     asset.Pair
+		strOutput string
+	}{
+		{name: "happy-0", input: asset.Pair("abc:xyz"), strOutput: "\"abc:xyz\""},
+		{name: "happy-1", input: asset.Pair("abc:xyz:foo"), strOutput: "\"abc:xyz:foo\""},
+		{name: "happy-2", input: asset.Pair("abc"), strOutput: "\"abc\""},
+		{name: "empty", input: asset.Pair(""), strOutput: "\"\""},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			// MarshalJSON with codec.LegacyAmino
+			jsonBz, err := cdc.Amino.MarshalJSON(tc.input)
+			require.NoError(t, err)
+			require.Equal(t, tc.strOutput, string(jsonBz))
+
+			// MarshalJSON on custom type
+			jsonBzCustom, err := tc.input.MarshalJSON()
+			require.NoError(t, err)
+			require.Equal(t, jsonBzCustom, jsonBz)
+
+			// UnmarshalJSON with codec.LegacyAmino
+			newPair := new(asset.Pair)
+			require.NoError(t, cdc.Amino.UnmarshalJSON(jsonBz, newPair))
+			require.Equal(t, tc.input, *newPair)
+
+			// UnmarshalJSON on custom type
+			newNewPair := new(asset.Pair)
+			*newNewPair = tc.input
+			require.NoError(t, newNewPair.UnmarshalJSON(jsonBz))
+
+			// Marshal and Unmarshal (to bytes) test
+			bz, err := tc.input.Marshal()
+			require.NoError(t, err)
+			newNewNewPair := new(asset.Pair)
+			require.NoError(t, newNewNewPair.Unmarshal(bz))
+			require.Equal(t, tc.input, *newNewNewPair)
+		})
+	}
+}
+
+func TestPairsUtils(t *testing.T) {
+	testCases := []struct {
+		pairStrs    []string
+		expectPanic bool
+	}{
+		{pairStrs: []string{"eth:usd", "btc:usd", "atom:usd"}, expectPanic: false},
+		{pairStrs: []string{"eth:usd", "", "abc"}, expectPanic: true},
+		{pairStrs: []string{"eth:usd:ftt", "btc:usd"}, expectPanic: true},
+	}
+
+	var panicTestFn func(t require.TestingT, f assert.PanicTestFunc, msgAndArgs ...interface{})
+
+	for idx, tc := range testCases {
+		t.Run(fmt.Sprint(idx), func(t *testing.T) {
+			if tc.expectPanic {
+				panicTestFn = require.Panics
+			} else {
+				panicTestFn = require.NotPanics
+			}
+			panicTestFn(t, func() {
+				pairs := asset.MustNewPairs(tc.pairStrs...)
+				newPairStrs := asset.PairsToStrings(pairs)
+				require.Equal(t, tc.pairStrs, newPairStrs)
+			})
+		})
+	}
+}

x/common/dec.go

@@ -10,7 +10,7 @@
 
 const (
 	// number of decimal places
-	Precision = 18
+	PrecisionExponent = 18
 
 	// bits required to represent the above precision
 	// Ceiling[Log2[10^Precision - 1]]
@@ -25,9 +25,11 @@
 )
 
 var (
-	precisionReuse = new(big.Int).Exp(big.NewInt(10), big.NewInt(Precision), nil)
-	fivePrecision  = new(big.Int).Quo(precisionReuse, big.NewInt(2))
-	oneInt         = big.NewInt(1)
+	// precisionInt: 10 ** PrecisionExponent
+	precisionInt = new(big.Int).Exp(big.NewInt(10), big.NewInt(PrecisionExponent), nil)
+	// halfPrecisionInt: (10 ** PrecisionExponent) / 2
+	halfPrecisionInt = new(big.Int).Quo(precisionInt, big.NewInt(2))
+	oneInt           = big.NewInt(1)
 )
 
 // MustSqrtDec computes the square root of the input decimal using its
@@ -119,8 +121,9 @@
 // |_____:  /   | $$$    |
 //              |________|
 
-// Remove a Precision amount of rightmost digits and perform bankers rounding
-// on the remainder (gaussian rounding) on the digits which have been removed.
+// ChopPrecisionAndRound: Remove a Precision amount of rightmost digits and
+// perform bankers rounding on the remainder (gaussian rounding) on the digits
+// which have been removed.
 //
 // Mutates the input. Use the non-mutative version if that is undesired
 func ChopPrecisionAndRound(d *big.Int) *big.Int {
@@ -133,20 +136,39 @@
 		return d
 	}
 
-	// get the truncated quotient and remainder
+	// Divide out the 'precisionInt', which truncates to a quotient and remainder.
 	quo, rem := d, big.NewInt(0)
-	quo, rem = quo.QuoRem(d, precisionReuse, rem)
+	quo, rem = quo.QuoRem(d, precisionInt, rem)
 
-	if rem.Sign() == 0 { // remainder is zero
+	return BankersRound(quo, rem, halfPrecisionInt)
+}
+
+// BankersRound: Banker's rounding is a method commonly used in banking and
+// accounting to reduce roudning bias when processing large volumes of rounded
+// numbers.
+//
+// 1. If the remainder < half precision, round down
+// 2. If the remainder > half precision, round up
+// 3. If remainder == half precision,  round to the nearest even number
+//
+// The name comes from the idea that it provides egalitarian rounding that
+// doesn't consistently favor one party over another (e.g. always rounding up).
+// With this method, rounding errors tend to cancel out rather than
+// accumulating in one direction.
+func BankersRound(quo, rem, halfPrecision *big.Int) *big.Int {
+	// Zero remainder after dividing precision means => no rounding is needed.
+	if rem.Sign() == 0 {
 		return quo
 	}
 
-	switch rem.Cmp(fivePrecision) {
+	// Nonzero remainder after dividing precision means => do banker's rounding
+	switch rem.Cmp(halfPrecision) {
 	case -1:
 		return quo
 	case 1:
 		return quo.Add(quo, oneInt)
-	default: // bankers rounding must take place
+	default:
+		// default case: bankers rounding must take place
 		// always round to an even number
 		if quo.Bit(0) == 0 {
 			return quo