tests(math): document unexpected behavior in nil values (#21806)

Author: kocubinski

Diff for: math/dec_test.go

@@ -1025,3 +1025,36 @@ func TestQuoMut(t *testing.T) {
 		})
 	}
 }
+
+func Test_DocumentLegacyAsymmetry(t *testing.T) {
+	zeroDec := math.LegacyZeroDec()
+	emptyDec := math.LegacyDec{}
+
+	zeroDecBz, err := zeroDec.Marshal()
+	require.NoError(t, err)
+	zeroDecJSON := zeroDec.String()
+
+	emptyDecBz, err := emptyDec.Marshal()
+	require.NoError(t, err)
+	emptyDecJSON := emptyDec.String()
+
+	// makes sense, zero and empty are semantically different and render differently
+	require.NotEqual(t, zeroDecJSON, emptyDecJSON)
+	// but on the proto wire they encode to the same bytes
+	require.Equal(t, zeroDecBz, emptyDecBz)
+
+	// zero values are symmetrical
+	zeroDecRoundTrip := math.LegacyDec{}
+	err = zeroDecRoundTrip.Unmarshal(zeroDecBz)
+	require.NoError(t, err)
+	require.Equal(t, zeroDec.String(), zeroDecRoundTrip.String())
+	require.Equal(t, zeroDec, zeroDecRoundTrip)
+
+	// empty values are not
+	emptyDecRoundTrip := math.LegacyDec{}
+	err = emptyDecRoundTrip.Unmarshal(emptyDecBz)
+	require.NoError(t, err)
+	// !!! this is the key point, they are not equal, it looks like a bug
+	require.NotEqual(t, emptyDec.String(), emptyDecRoundTrip.String())
+	require.NotEqual(t, emptyDec, emptyDecRoundTrip)
+}