Merge pull request #1691 from lightninglabs/multi-bug-fix

Improve grouped asset UX for onchain and offchain balances

Author: GeorgeTsagk

docs/release-notes/release-notes-0.7.0.md

@@ -66,6 +66,7 @@
   [API
   docs](https://lightning.engineering/api-docs/api/taproot-assets/price-oracle/query-asset-rates/#priceoraclerpcintent)
   for more information on the different values and their meaning.
+
 - The `SendPayment`, `AddInvoice` and `DecodeAssetPayReq` RPCs now have a [new
   `price_oracle_metadata` field the user can specify to send additional metadata
   to a price oracle](https://github.com/lightninglabs/taproot-assets/pull/1677)
@@ -79,6 +80,11 @@
   completed sends with efficient database-level
   filtering](https://github.com/lightninglabs/taproot-assets/pull/1685).
 
+- A [new field `unconfirmed_transfers` was added to the response of the 
+  `ListBalances` RPC
+  method](https://github.com/lightninglabs/taproot-assets/pull/1691) to indicate
+  that unconfirmed asset-related transactions don't count toward the balance.
+
 ## tapcli Additions
 
 - [Rename](https://github.com/lightninglabs/taproot-assets/pull/1682) the mint
@@ -93,6 +99,10 @@
 
 ## Functional Updates
 
+- The output of `lncli channelbalance` [now also shows the local and remote
+  balances of asset channels grouped by group key (if grouped assets were used
+  in a channel)](https://github.com/lightninglabs/taproot-assets/pull/1691).
+
 ## RPC Updates
 
 ## tapcli Updates

itest/assertions.go

@@ -2279,6 +2279,24 @@ func AssertBalances(t *testing.T, client taprpc.TaprootAssetsClient,
 			"asset balance, wanted %d, got: %v", balance,
 			toJSON(t, assetIDBalances),
 		)
+
+		// If we query for grouped asset balances too, it means we do
+		// have at least some assets with a group key. So the output of
+		// the ListBalances call should contain at least one asset
+		// balance with a group key set.
+		if config.groupedAssetBalance > 0 {
+			numGrouped := 0
+			for _, bal := range assetIDBalances.AssetBalances {
+				if len(bal.GroupKey) > 0 {
+					numGrouped++
+				}
+			}
+			require.Greater(
+				t, numGrouped, 0, "expected at least one "+
+					"asset in ListBalances response to "+
+					"have a group key set",
+			)
+		}
 	}
 
 	// Next, we do the same but grouped by group keys (if requested, since
@@ -2305,6 +2323,12 @@ func AssertBalances(t *testing.T, client taprpc.TaprootAssetsClient,
 				"grouped balance, wanted %d, got: %v", balance,
 				toJSON(t, assetGroupBalances),
 			)
+
+			// Because we query for grouped assets, the group key
+			// field should be set for all asset balances.
+			for _, bal := range assetGroupBalances.AssetBalances {
+				require.Equal(t, config.groupKey, bal.GroupKey)
+			}
 		}
 	}
 

rfqmsg/custom_channel_data.go

@@ -10,8 +10,8 @@ import (
 // JsonAssetBalance is a struct that represents the balance of a single asset ID
 // within a channel.
 type JsonAssetBalance struct {
-	AssetID       string `json:"asset_id"`
-	Name          string `json:"name"`
+	AssetID       string `json:"asset_id,omitempty"`
+	Name          string `json:"name,omitempty"`
 	LocalBalance  uint64 `json:"local_balance"`
 	RemoteBalance uint64 `json:"remote_balance"`
 }
@@ -80,9 +80,12 @@ func (c *JsonAssetChannel) HasAllAssetIDs(ids fn.Set[asset.ID]) bool {
 
 // JsonAssetChannelBalances is a struct that represents the balance information
 // of all assets within open and pending channels.
+// nolint:lll
 type JsonAssetChannelBalances struct {
-	OpenChannels    map[string]*JsonAssetBalance `json:"open_channels"`
-	PendingChannels map[string]*JsonAssetBalance `json:"pending_channels"`
+	OpenChannels           map[string]*JsonAssetBalance `json:"open_channels"`
+	OpenChannelsByGroup    map[string]*JsonAssetBalance `json:"open_channels_by_group"`
+	PendingChannels        map[string]*JsonAssetBalance `json:"pending_channels"`
+	PendingChannelsByGroup map[string]*JsonAssetBalance `json:"pending_channels_by_group"`
 }
 
 // JsonCloseOutput is a struct that represents the additional co-op close output

rpcserver.go

@@ -1275,12 +1275,12 @@ func (r *rpcServer) listBalancesByAsset(ctx context.Context,
 	}
 
 	resp := &taprpc.ListBalancesResponse{
-		AssetBalances: make(map[string]*taprpc.AssetBalance, len(balances)),
+		AssetBalances: make(
+			map[string]*taprpc.AssetBalance, len(balances),
+		),
 	}
 
 	for _, balance := range balances {
-		balance := balance
-
 		assetIDStr := hex.EncodeToString(balance.ID[:])
 
 		resp.AssetBalances[assetIDStr] = &taprpc.AssetBalance{
@@ -1291,10 +1291,21 @@ func (r *rpcServer) listBalancesByAsset(ctx context.Context,
 				MetaHash:     balance.MetaHash[:],
 				AssetId:      balance.ID[:],
 			},
-			Balance: balance.Balance,
+			GroupKey: balance.GroupKey,
+			Balance:  balance.Balance,
 		}
 	}
 
+	// We will also report the number of unconfirmed transfers. This is
+	// useful for clients as unconfirmed asset coins are not included in the
+	// balance list.
+	outboundParcels, err := r.cfg.AssetStore.QueryParcels(ctx, nil, true)
+	if err != nil {
+		return nil, fmt.Errorf("unable to query for unconfirmed "+
+			"outgoing parcels: %w", err)
+	}
+	resp.UnconfirmedTransfers = uint64(len(outboundParcels))
+
 	return resp, nil
 }
 
@@ -1331,6 +1342,16 @@ func (r *rpcServer) listBalancesByGroupKey(ctx context.Context,
 		}
 	}
 
+	// We will also report the number of unconfirmed transfers. This is
+	// useful for clients as unconfirmed asset coins are not included in the
+	// balance list.
+	outboundParcels, err := r.cfg.AssetStore.QueryParcels(ctx, nil, true)
+	if err != nil {
+		return nil, fmt.Errorf("unable to query for unconfirmed "+
+			"outgoing parcels: %w", err)
+	}
+	resp.UnconfirmedTransfers = uint64(len(outboundParcels))
+
 	return resp, nil
 }
 

tapchannelmsg/custom_channel_data.go

@@ -200,83 +200,90 @@ func (b *BalanceCustomData) AsJson() ([]byte, error) {
 		return []byte{}, nil
 	}
 
-	resp := &rfqmsg.JsonAssetChannelBalances{
-		OpenChannels:    make(map[string]*rfqmsg.JsonAssetBalance),
-		PendingChannels: make(map[string]*rfqmsg.JsonAssetBalance),
-	}
-	for _, openChan := range b.OpenChannels {
-		for _, assetOutput := range openChan.LocalOutputs() {
-			assetID := assetOutput.AssetID.Val
+	type groupedBalance = map[string]*rfqmsg.JsonAssetBalance
 
-			assetIDStr := hex.EncodeToString(assetID[:])
-			assetName := assetOutput.Proof.Val.Asset.Tag
+	// addOutput is a helper function that adds an asset output to the
+	// targetByID and targetByGroup maps, updating the local or remote
+	// balance as appropriate.
+	addOutput := func(out *AssetOutput, local bool, targetByID,
+		targetByGroup groupedBalance) {
 
-			assetBalance, ok := resp.OpenChannels[assetIDStr]
-			if !ok {
-				assetBalance = &rfqmsg.JsonAssetBalance{
-					AssetID: assetIDStr,
-					Name:    assetName,
-				}
-				resp.OpenChannels[assetIDStr] = assetBalance
-			}
+		assetID := out.AssetID.Val
+		assetIDStr := hex.EncodeToString(assetID[:])
+		assetName := out.Proof.Val.Asset.Tag
+		amount := out.Amount.Val
+		groupKey := out.Proof.Val.Asset.GroupKey
 
-			assetBalance.LocalBalance += assetOutput.Amount.Val
+		balanceByID, ok := targetByID[assetIDStr]
+		if !ok {
+			balanceByID = &rfqmsg.JsonAssetBalance{
+				AssetID: assetIDStr,
+				Name:    assetName,
+			}
+			targetByID[assetIDStr] = balanceByID
 		}
 
-		for _, assetOutput := range openChan.RemoteOutputs() {
-			assetID := assetOutput.AssetID.Val
+		if local {
+			balanceByID.LocalBalance += amount
+		} else {
+			balanceByID.RemoteBalance += amount
+		}
 
-			assetIDStr := hex.EncodeToString(assetID[:])
-			assetName := assetOutput.Proof.Val.Asset.Tag
+		if groupKey != nil {
+			groupKeyStr := hex.EncodeToString(
+				groupKey.GroupPubKey.SerializeCompressed(),
+			)
 
-			assetBalance, ok := resp.OpenChannels[assetIDStr]
+			balanceByGroupKey, ok := targetByGroup[groupKeyStr]
 			if !ok {
-				assetBalance = &rfqmsg.JsonAssetBalance{
-					AssetID: assetIDStr,
-					Name:    assetName,
-				}
-				resp.OpenChannels[assetIDStr] = assetBalance
+				balanceByGroupKey = &rfqmsg.JsonAssetBalance{}
+				targetByGroup[groupKeyStr] = balanceByGroupKey
 			}
 
-			assetBalance.RemoteBalance += assetOutput.Amount.Val
+			if local {
+				balanceByGroupKey.LocalBalance += amount
+			} else {
+				balanceByGroupKey.RemoteBalance += amount
+			}
 		}
 	}
 
-	for _, pendingChan := range b.PendingChannels {
-		for _, assetOutput := range pendingChan.LocalOutputs() {
-			assetID := assetOutput.AssetID.Val
+	resp := &rfqmsg.JsonAssetChannelBalances{
+		OpenChannels:           make(groupedBalance),
+		OpenChannelsByGroup:    make(groupedBalance),
+		PendingChannels:        make(groupedBalance),
+		PendingChannelsByGroup: make(groupedBalance),
+	}
 
-			assetIDStr := hex.EncodeToString(assetID[:])
-			assetName := assetOutput.Proof.Val.Asset.Tag
+	for _, openChan := range b.OpenChannels {
+		for _, assetOutput := range openChan.LocalOutputs() {
+			addOutput(
+				assetOutput, true, resp.OpenChannels,
+				resp.OpenChannelsByGroup,
+			)
+		}
 
-			assetBalance, ok := resp.PendingChannels[assetIDStr]
-			if !ok {
-				assetBalance = &rfqmsg.JsonAssetBalance{
-					AssetID: assetIDStr,
-					Name:    assetName,
-				}
-				resp.PendingChannels[assetIDStr] = assetBalance
-			}
+		for _, assetOutput := range openChan.RemoteOutputs() {
+			addOutput(
+				assetOutput, false, resp.OpenChannels,
+				resp.OpenChannelsByGroup,
+			)
+		}
+	}
 
-			assetBalance.LocalBalance += assetOutput.Amount.Val
+	for _, pendingChan := range b.PendingChannels {
+		for _, assetOutput := range pendingChan.LocalOutputs() {
+			addOutput(
+				assetOutput, true, resp.PendingChannels,
+				resp.PendingChannelsByGroup,
+			)
 		}
 
 		for _, assetOutput := range pendingChan.RemoteOutputs() {
-			assetID := assetOutput.AssetID.Val
-
-			assetIDStr := hex.EncodeToString(assetID[:])
-			assetName := assetOutput.Proof.Val.Asset.Tag
-
-			assetBalance, ok := resp.PendingChannels[assetIDStr]
-			if !ok {
-				assetBalance = &rfqmsg.JsonAssetBalance{
-					AssetID: assetIDStr,
-					Name:    assetName,
-				}
-				resp.PendingChannels[assetIDStr] = assetBalance
-			}
-
-			assetBalance.RemoteBalance += assetOutput.Amount.Val
+			addOutput(
+				assetOutput, false, resp.PendingChannels,
+				resp.PendingChannelsByGroup,
+			)
 		}
 	}
 

tapchannelmsg/custom_channel_data_test.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/btcsuite/btcd/btcec/v2"
 	"github.com/btcsuite/btcd/wire"
+	"github.com/lightninglabs/taproot-assets/asset"
 	"github.com/lightninglabs/taproot-assets/fn"
 	"github.com/lightninglabs/taproot-assets/internal/test"
 	"github.com/lightninglabs/taproot-assets/rfqmsg"
@@ -137,6 +138,16 @@ func TestReadBalanceCustomData(t *testing.T) {
 	proof1 := randProof(t)
 	proof2 := randProof(t)
 	proof3 := randProof(t)
+
+	// We make it so the assets in proof 1 and proof 2 are in the same
+	// group, so their balance will be combined in the output.
+	groupPubKey := test.RandPubKey(t)
+	proof1.Asset.GroupKey = &asset.GroupKey{
+		GroupPubKey: *groupPubKey,
+	}
+	proof2.Asset.GroupKey = proof1.Asset.GroupKey
+	groupKeyStr := hex.EncodeToString(groupPubKey.SerializeCompressed())
+
 	assetID1 := proof1.Asset.ID()
 	assetID2 := proof2.Asset.ID()
 	assetID3 := proof3.Asset.ID()
@@ -226,6 +237,20 @@ func TestReadBalanceCustomData(t *testing.T) {
 	require.Contains(t, formattedJSON.String(), expectedOpen3)
 	require.Contains(t, formattedJSON.String(), expectedPending1)
 	require.Contains(t, formattedJSON.String(), expectedPending2)
+
+	// The grouped balance shouldn't show the asset ID or name, since that
+	// would be confusing as it would only use the ID/name of the first
+	// asset we have in the channels for that group.
+	expectedOpenGroup := `"` + groupKeyStr + `": {
+      "local_balance": 3000,
+      "remote_balance": 2000
+    }`
+	expectedPendingGroup := `"` + groupKeyStr + `": {
+      "local_balance": 0,
+      "remote_balance": 1000
+    }`
+	require.Contains(t, formattedJSON.String(), expectedOpenGroup)
+	require.Contains(t, formattedJSON.String(), expectedPendingGroup)
 }
 
 // TestCloseOutCustomData tests that we can read the custom data from a channel

tapdb/assets_store.go

@@ -383,6 +383,7 @@ type AssetBalance struct {
 	Type         asset.Type
 	GenesisPoint wire.OutPoint
 	OutputIndex  uint32
+	GroupKey     []byte
 }
 
 // AssetGroupBalance holds abalance query result for a particular asset group
@@ -1064,6 +1065,7 @@ func (a *AssetStore) QueryBalancesByAsset(ctx context.Context,
 				Tag:         assetBalance.AssetTag,
 				Type:        asset.Type(assetBalance.AssetType),
 				OutputIndex: uint32(assetBalance.OutputIndex),
+				GroupKey:    assetBalance.GroupKey,
 			}
 
 			err = readOutPoint(