multi: add decimal display as new TLV field

With this commit we add the decimal display as a new TLV field on the
meta reveal. We'll still encode it within the JSON meta data if the meta
data is of type JSON. For all other types we can now also carry the
value, to make sure we don't put any type constraints on future asset
mints (in case issuers want to use a different format than JSON).

Since we're using TLV, old meta reveals should still be read correctly
and the default value of 0 is assumed for any meta reveal that doesn't
have the explicit record set.
We'll add a unit test for that in the next commit.

Author: guggero

itest/assertions.go

@@ -1852,22 +1852,19 @@ func AssertAssetsMinted(t *testing.T, tapClient commands.RpcClientsBundle,
 	confirmedAssets := GroupAssetsByName(listRespConfirmed.Assets)
 
 	for _, assetRequest := range assetRequests {
-		metaReveal := &proof.MetaReveal{
-			Data: assetRequest.Asset.AssetMeta.Data,
-		}
-
 		validMetaType, err := proof.IsValidMetaType(
 			assetRequest.Asset.AssetMeta.Type,
 		)
 		require.NoError(t, err)
 
-		metaReveal.Type = validMetaType
-		if metaReveal.Type == proof.MetaJson {
-			err := metaReveal.SetDecDisplay(
-				assetRequest.Asset.DecimalDisplay,
-			)
-			require.NoError(t, err)
+		metaReveal := &proof.MetaReveal{
+			Data: assetRequest.Asset.AssetMeta.Data,
+			Type: validMetaType,
 		}
+		err = metaReveal.SetDecDisplay(
+			assetRequest.Asset.DecimalDisplay,
+		)
+		require.NoError(t, err)
 
 		metaHash := metaReveal.MetaHash()
 
@@ -2077,10 +2074,15 @@ func assertGroups(t *testing.T, client taprpc.TaprootAssetsClient,
 	equalityCheck := func(a *mintrpc.MintAsset,
 		b *taprpc.AssetHumanReadable) {
 
-		metaHash := (&proof.MetaReveal{
+		assetMeta := &proof.MetaReveal{
 			Type: proof.MetaOpaque,
 			Data: a.AssetMeta.Data,
-		}).MetaHash()
+		}
+
+		err = assetMeta.SetDecDisplay(a.DecimalDisplay)
+		require.NoError(t, err)
+
+		metaHash := assetMeta.MetaHash()
 
 		require.Equal(t, a.AssetType, b.Type)
 		require.Equal(t, a.Name, b.Tag)

itest/asset_meta_test.go

@@ -167,31 +167,83 @@ func testMintAssetWithDecimalDisplayMetaField(t *harnessTest) {
 	secondAssetReq.Asset.GroupKey = groupKey
 	secondAssetReq.Asset.DecimalDisplay = 0
 
-	// Reissuance should fail if the decimal display does not match the
+	// Re-issuance should fail if the decimal display does not match the
 	// group anchor.
 	_, err = t.tapd.MintAsset(ctxt, secondAssetReq)
 	require.ErrorContains(t.t, err, "decimal display does not match")
 
-	// Requesting a decimal display without specifying the metadata type as
-	// JSON should fail.
+	// Requesting a decimal display without specifying the metadata field
+	// with at least the type should fail.
 	secondAssetReq.Asset.DecimalDisplay = firstAsset.DecimalDisplay
 	secondAssetReq.Asset.AssetMeta = nil
 
 	_, err = t.tapd.MintAsset(ctxt, secondAssetReq)
-	require.ErrorContains(t.t, err, "decimal display requires JSON")
+	require.ErrorContains(
+		t.t, err, "decimal display requires asset metadata",
+	)
 
-	// If we update the decimal display to match the group anchor, minting
-	// should succeed. We also unset the metadata to ensure that the decimal
-	// display is set as the sole JSON object if needed.
+	// Attempting to set a different decimal display in the JSON meta data
+	// as in the new RPC request field should give us an error as well.
 	secondAssetReq.Asset.AssetMeta = &taprpc.AssetMeta{
 		Type: taprpc.AssetMetaType_META_TYPE_JSON,
+		Data: []byte(`{"foo": "bar", "decimal_display": 3}`),
 	}
-	MintAssetsConfirmBatch(
+	_, err = t.tapd.MintAsset(ctxt, secondAssetReq)
+	require.ErrorContains(
+		t.t, err, "decimal display in JSON asset meta does not match",
+	)
+
+	// If we set a valid asset meta again, minting should succeed, using the
+	// same decimal display as the group anchor.
+	secondAssetReq.Asset.AssetMeta.Data = []byte(`{"foo": "bar"}`)
+	secondAssets := MintAssetsConfirmBatch(
 		t.t, t.lndHarness.Miner().Client, t.tapd,
 		[]*mintrpc.MintAssetRequest{secondAssetReq},
 	)
+	require.Len(t.t, secondAssets, 1)
+	require.NotNil(t.t, secondAssets[0].DecimalDisplay)
+	require.EqualValues(
+		t.t, 2, secondAssets[0].DecimalDisplay.DecimalDisplay,
+	)
+
+	// For an asset with a JSON meta data type, we also expect the decimal
+	// display to be encoded in the meta data JSON.
+	metaResp, err := t.tapd.FetchAssetMeta(
+		ctxt, &taprpc.FetchAssetMetaRequest{
+			Asset: &taprpc.FetchAssetMetaRequest_AssetId{
+				AssetId: secondAssets[0].AssetGenesis.AssetId,
+			},
+		},
+	)
+	require.NoError(t.t, err)
+	require.Contains(t.t, string(metaResp.Data), `"foo":"bar"`)
+	require.Contains(t.t, string(metaResp.Data), `"decimal_display":2`)
 
 	AssertGroupSizes(
 		t.t, t.tapd, []string{hex.EncodeToString(groupKey)}, []int{2},
 	)
+
+	// Now we also test minting an asset that uses the opaque meta data type
+	// and check that the decimal display is correctly encoded as well.
+	thirdAsset := &mintrpc.MintAsset{
+		AssetType: taprpc.AssetType_NORMAL,
+		Name:      "test-asset-opaque-decimal-display",
+		AssetMeta: &taprpc.AssetMeta{
+			Type: taprpc.AssetMetaType_META_TYPE_OPAQUE,
+			Data: []byte("some opaque data"),
+		},
+		Amount:         123,
+		DecimalDisplay: 7,
+	}
+	thirdAssetReq := &mintrpc.MintAssetRequest{Asset: thirdAsset}
+	thirdAssets := MintAssetsConfirmBatch(
+		t.t, t.lndHarness.Miner().Client, t.tapd,
+		[]*mintrpc.MintAssetRequest{thirdAssetReq},
+	)
+
+	require.Len(t.t, thirdAssets, 1)
+	require.NotNil(t.t, thirdAssets[0].DecimalDisplay)
+	require.EqualValues(
+		t.t, 7, thirdAssets[0].DecimalDisplay.DecimalDisplay,
+	)
 }

itest/utils.go

@@ -427,12 +427,10 @@ func FinalizeBatchUnconfirmed(t *testing.T, minerClient *rpcclient.Client,
 		require.NoError(t, err)
 
 		metaReveal.Type = validMetaType
-		if metaReveal.Type == proof.MetaJson {
-			err := metaReveal.SetDecDisplay(
-				assetRequest.Asset.DecimalDisplay,
-			)
-			require.NoError(t, err)
-		}
+		err = metaReveal.SetDecDisplay(
+			assetRequest.Asset.DecimalDisplay,
+		)
+		require.NoError(t, err)
 
 		metaHash := metaReveal.MetaHash()
 
@@ -604,6 +602,9 @@ func ManualMintSimpleAsset(t *harnessTest, lndNode *node.HarnessNode,
 		Type: proof.MetaOpaque,
 		Data: req.AssetMeta.Data,
 	}
+	err = assetMeta.SetDecDisplay(req.DecimalDisplay)
+	require.NoError(t.t, err)
+
 	metaHash := assetMeta.MetaHash()
 	metaReveals := tapgarden.AssetMetas{
 		asset.ToSerialized(assetScriptKey.PubKey): &assetMeta,

proof/encoding.go

@@ -9,6 +9,7 @@ import (
 	"github.com/btcsuite/btcd/blockchain"
 	"github.com/btcsuite/btcd/wire"
 	"github.com/lightninglabs/taproot-assets/asset"
+	"github.com/lightninglabs/taproot-assets/fn"
 	"github.com/lightningnetwork/lnd/tlv"
 )
 
@@ -463,3 +464,39 @@ func GenesisRevealDecoder(r io.Reader, val any, buf *[8]byte, l uint64) error {
 
 	return tlv.NewTypeForEncodingErr(val, "GenesisReveal")
 }
+
+// EUint32Option encodes a uint32 option. If the value is not set, we'll encode
+// it as a zero-length record. But that means that the type and length fields
+// will still be encoded, which is different from the record not being present
+// at all. If the distinction should be made (e.g. to not re-encode old records
+// that didn't have that field at all with the new zero-length record), the
+// caller needs to handle that by conditionally including or not including the
+// record.
+func EUint32Option(w io.Writer, val interface{}, buf *[8]byte) error {
+	if t, ok := val.(*fn.Option[uint32]); ok {
+		return fn.MapOptionZ(*t, func(value uint32) error {
+			return tlv.EUint32T(w, value, buf)
+		})
+	}
+	return tlv.NewTypeForEncodingErr(val, "*fn.Option[uint32]")
+}
+
+// DUint32Option decodes a uint32 option.
+func DUint32Option(r io.Reader, val interface{}, buf *[8]byte, l uint64) error {
+	if t, ok := val.(*fn.Option[uint32]); ok {
+		if l == 0 {
+			*t = fn.None[uint32]()
+			return nil
+		}
+
+		var newVal uint32
+		if err := tlv.DUint32(r, &newVal, buf, l); err != nil {
+			return err
+		}
+
+		*t = fn.Some(newVal)
+
+		return nil
+	}
+	return tlv.NewTypeForDecodingErr(val, "*fn.Option[uint32]", l, l)
+}

proof/meta.go

@@ -100,6 +100,16 @@ type MetaReveal struct {
 	// Data is the committed data being revealed.
 	Data []byte
 
+	// DecimalDisplay is the decimal display value of the asset. This is
+	// used to determine the number of decimal places to display when
+	// presenting the asset amount to the user. If this field is not
+	// explicitly encoded in the TLV, this is an older asset that didn't
+	// have this field. New assets will always set an explicit value, even
+	// if that is the default value of zero. If the meta type is JSON and
+	// this value is not zero, then the decimal display is also added as a
+	// field to the JSON object for backward compatibility.
+	DecimalDisplay fn.Option[uint32]
+
 	// UnknownOddTypes is a map of unknown odd types that were encountered
 	// during decoding. This map is used to preserve unknown types that we
 	// don't know of yet, so we can still encode them back when serializing.
@@ -141,7 +151,8 @@ func (m *MetaReveal) Validate() error {
 		}
 	}
 
-	return nil
+	// If the decimal display is set, it must be valid.
+	return fn.MapOptionZ(m.DecimalDisplay, IsValidDecDisplay)
 }
 
 // IsValidMetaType checks if the passed value is a valid meta type.
@@ -232,6 +243,12 @@ func (m *MetaReveal) GetDecDisplay() (map[string]interface{}, uint32, error) {
 		return nil, 0, nil
 	}
 
+	// If the decimal display is set as the new TLV value, we can use that
+	// directly.
+	if m.DecimalDisplay.IsSome() {
+		return nil, m.DecimalDisplay.UnwrapOr(0), nil
+	}
+
 	if m.Type != MetaJson {
 		return nil, 0, ErrNotJSON
 	}
@@ -311,9 +328,18 @@ func (m *MetaReveal) SetDecDisplay(decDisplay uint32) error {
 		return err
 	}
 
-	// If the meta type is not JSON, we can't set the decimal display value.
+	m.DecimalDisplay = fn.Some(decDisplay)
+
+	// We only set the decimal display value in the JSON if it isn't the
+	// default value of 0.
+	if decDisplay == 0 {
+		return nil
+	}
+
+	// If the meta type is not JSON, we're done already, as the decimal
+	// display will only be encoded in the TLV.
 	if m.Type != MetaJson {
-		return ErrNotJSON
+		return nil
 	}
 
 	// If the meta type is JSON, we'll also want to set the decimal display
@@ -359,6 +385,15 @@ func (m *MetaReveal) EncodeRecords() []tlv.Record {
 		MetaRevealDataRecord(&m.Data),
 	}
 
+	// To make sure we don't re-encode old assets that don't have a decimal
+	// display value as a TLV field with a different value, we only encode
+	// the decimal display value if it is explicitly set.
+	if m.DecimalDisplay.IsSome() {
+		records = append(records, MetaRevealDecimalDisplayRecord(
+			&m.DecimalDisplay,
+		))
+	}
+
 	// Add any unknown odd types that were encountered during decoding.
 	return asset.CombineRecords(records, m.UnknownOddTypes)
 }
@@ -368,6 +403,7 @@ func (m *MetaReveal) DecodeRecords() []tlv.Record {
 	return []tlv.Record{
 		MetaRevealTypeRecord(&m.Type),
 		MetaRevealDataRecord(&m.Data),
+		MetaRevealDecimalDisplayRecord(&m.DecimalDisplay),
 	}
 }
 

proof/records.go

@@ -43,8 +43,9 @@ const (
 	TapscriptProofTapPreimage2 tlv.Type = 3
 	TapscriptProofBip86        tlv.Type = 4
 
-	MetaRevealEncodingType tlv.Type = 0
-	MetaRevealDataType     tlv.Type = 2
+	MetaRevealEncodingType   tlv.Type = 0
+	MetaRevealDataType       tlv.Type = 2
+	MetaRevealDecimalDisplay tlv.Type = 5
 )
 
 // KnownProofTypes is a set of all known proof TLV types. This set is asserted
@@ -83,7 +84,7 @@ var KnownTapscriptProofTypes = fn.NewSet(
 // KnownMetaRevealTypes is a set of all known meta reveal TLV types. This set is
 // asserted to be complete by a check in the BIP test vector unit tests.
 var KnownMetaRevealTypes = fn.NewSet(
-	MetaRevealEncodingType, MetaRevealDataType,
+	MetaRevealEncodingType, MetaRevealDataType, MetaRevealDecimalDisplay,
 )
 
 func VersionRecord(version *TransitionVersion) tlv.Record {
@@ -362,6 +363,24 @@ func MetaRevealDataRecord(data *[]byte) tlv.Record {
 	)
 }
 
+func MetaRevealDecimalDisplayRecord(
+	decimalDisplay *fn.Option[uint32]) tlv.Record {
+
+	// If the option is not set, we'll encode it as a zero-length record.
+	// But because we'll not include the record at all if it's not set at
+	// the call site when encoding, this will not be the case for this
+	// specific record.
+	var size uint64
+	if decimalDisplay != nil && decimalDisplay.IsSome() {
+		size = 4
+	}
+
+	return tlv.MakeStaticRecord(
+		MetaRevealDecimalDisplay, decimalDisplay, size,
+		EUint32Option, DUint32Option,
+	)
+}
+
 func GenesisRevealRecord(genesis **asset.Genesis) tlv.Record {
 	recordSize := func() uint64 {
 		var (