feat: add ValueCodec for time.Time (#25827)

Co-authored-by: Alex | Cosmos Labs <alex@cosmoslabs.io>

Author: neyy91

CHANGELOG.md

@@ -67,6 +67,7 @@ Ref: https://keepachangelog.com/en/1.0.0/
 * [#25516](https://github.com/cosmos/cosmos-sdk/pull/25516) Support automatic configuration of OpenTelemetry via [OpenTelemetry declarative configuration](https://pkg.go.dev/go.opentelemetry.io/contrib/otelconf) and add OpenTelemetry instrumentation of `BaseApp`.
 * [#25745](https://github.com/cosmos/cosmos-sdk/pull/25745) Add DiskIO telemetry via gopsutil.
 * (grpc) [#25648](https://github.com/cosmos/cosmos-sdk/pull/25648) Add `earliest_block_height` and `latest_block_height` fields to `GetSyncingResponse`.
+* (collections/codec) [#25614] (https://github.com/cosmos/cosmos-sdk/pull/25827)  Add `TimeValue` (`ValueCodec[time.Time]`) to collections/codec.
 * (enterprise/poa) [#25838](https://github.com/cosmos/cosmos-sdk/pull/25838) Add the `poa` module under the `enterprise` directory.
 
 ### Improvements

collections/codec/time.go

@@ -0,0 +1,65 @@
+package codec
+
+import (
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"time"
+)
+
+// TimeValue returns a ValueCodec for time.Time.
+//
+// Binary format: 8 bytes (big-endian) of int64 UnixNano.
+// JSON format: RFC3339Nano string.
+func TimeValue() ValueCodec[time.Time] {
+	return timeValueCodec{}
+}
+
+type timeValueCodec struct{}
+
+func (timeValueCodec) Encode(value time.Time) ([]byte, error) {
+	value = value.UTC()
+	n := value.UnixNano()
+
+	b := make([]byte, 8)
+	binary.BigEndian.PutUint64(b, uint64(n))
+	return b, nil
+}
+
+func (timeValueCodec) Decode(b []byte) (time.Time, error) {
+	if len(b) != 8 {
+		return time.Time{}, fmt.Errorf("%w: invalid buffer size, wanted: 8", ErrEncoding)
+	}
+
+	n := int64(binary.BigEndian.Uint64(b))
+	return time.Unix(0, n).UTC(), nil
+}
+
+func (timeValueCodec) EncodeJSON(value time.Time) ([]byte, error) {
+	s := value.UTC().Format(time.RFC3339Nano)
+	return json.Marshal(s)
+}
+
+func (timeValueCodec) DecodeJSON(b []byte) (time.Time, error) {
+	var s string
+	if err := json.Unmarshal(b, &s); err != nil {
+		return time.Time{}, err
+	}
+
+	t, err := time.Parse(time.RFC3339Nano, s)
+	if err != nil {
+		return time.Time{}, err
+	}
+
+	return t.UTC(), nil
+}
+
+func (timeValueCodec) Stringify(value time.Time) string {
+	return value.UTC().Format(time.RFC3339Nano)
+}
+
+func (timeValueCodec) ValueType() string {
+	return "time"
+}
+
+var _ ValueCodec[time.Time] = timeValueCodec{}

collections/codec/time_test.go

@@ -0,0 +1,56 @@
+package codec
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestTimeValue_BinaryRoundTrip(t *testing.T) {
+	cdc := TimeValue()
+
+	tt := time.Date(2026, 1, 25, 12, 34, 56, 123456789, time.UTC)
+
+	b, err := cdc.Encode(tt)
+	require.NoError(t, err)
+	require.Len(t, b, 8)
+
+	got, err := cdc.Decode(b)
+	require.NoError(t, err)
+
+	require.True(t, tt.Equal(got))
+	require.Equal(t, time.UTC, got.Location())
+}
+
+func TestTimeValue_BinaryInvalidLen(t *testing.T) {
+	cdc := TimeValue()
+
+	_, err := cdc.Decode([]byte{1, 2, 3})
+	require.Error(t, err)
+}
+
+func TestTimeValue_JSONRoundTrip(t *testing.T) {
+	cdc := TimeValue()
+
+	tt := time.Date(2026, 1, 25, 12, 34, 56, 123456789, time.UTC)
+
+	b, err := cdc.EncodeJSON(tt)
+	require.NoError(t, err)
+
+	got, err := cdc.DecodeJSON(b)
+	require.NoError(t, err)
+
+	require.True(t, tt.Equal(got))
+	require.Equal(t, time.UTC, got.Location())
+}
+
+func TestTimeValue_Stringify(t *testing.T) {
+	cdc := TimeValue()
+
+	tt := time.Date(2026, 1, 25, 12, 34, 56, 123456789, time.UTC)
+	s := cdc.Stringify(tt)
+
+	require.Contains(t, s, "2026-01-25T12:34:56")
+	require.Contains(t, s, "Z")
+}