taprpc+tapcli: expose channel and pending asset balances

cmd/commands/assets.go

@@ -131,6 +131,8 @@ const (
 	burnOverrideConfirmationName  = "override_confirmation_destroy_assets"
 	scriptKeyTypeName             = "script_key_type"
 	scriptKeyTypeAll              = "all_script_key_types"
+	includeChannelName            = "include_channel"
+	includePendingName            = "include_pending"
 )
 
 var mintAssetCommand = cli.Command{
@@ -715,8 +717,8 @@ func listBatches(ctx *cli.Context) error {
 var listAssetsCommand = cli.Command{
 	Name:        "list",
 	ShortName:   "l",
-	Usage:       "list all assets",
-	Description: "list all pending and mined assets",
+	Usage:       "list on-chain assets",
+	Description: "list pending and mined on-chain assets",
 	Flags: []cli.Flag{
 		cli.BoolFlag{
 			Name:  assetShowWitnessName,
@@ -762,6 +764,16 @@ var listAssetsCommand = cli.Command{
 				"(asc or desc). Defaults to desc.",
 			Value: "desc",
 		},
+		cli.BoolFlag{
+			Name: includeChannelName,
+			Usage: "include assets used for funding " +
+				"custom channels in the list",
+		},
+		cli.BoolFlag{
+			Name: includePendingName,
+			Usage: "include local outputs from " +
+				"unconfirmed outbound transfers",
+		},
 	},
 	Action: listAssets,
 }
@@ -792,6 +804,8 @@ func listAssets(ctx *cli.Context) error {
 		Limit:                   int32(ctx.Int64(limitName)),
 		Offset:                  int32(ctx.Int64(offsetName)),
 		Direction:               direction,
+		IncludeChannel:          ctx.Bool(includeChannelName),
+		IncludePendingTransfers: ctx.Bool(includePendingName),
 	})
 	if err != nil {
 		return fmt.Errorf("unable to list assets: %w", err)
@@ -897,8 +911,8 @@ func fetchAsset(ctx *cli.Context) error {
 var listUtxosCommand = cli.Command{
 	Name:        "utxos",
 	ShortName:   "u",
-	Usage:       "list all utxos",
-	Description: "list all utxos managing assets",
+	Usage:       "list on-chain utxos",
+	Description: "list utxos managing on-chain assets",
 	Flags: []cli.Flag{
 		cli.BoolFlag{
 			Name:  assetShowLeasedName,
@@ -917,6 +931,11 @@ var listUtxosCommand = cli.Command{
 				"key type; cannot be used at the same time " +
 				"as --" + scriptKeyTypeName,
 		},
+		cli.BoolFlag{
+			Name: includeChannelName,
+			Usage: "include UTXOs that contain assets " +
+				"used for funding custom channels",
+		},
 	},
 	Action: listUtxos,
 }
@@ -932,8 +951,9 @@ func listUtxos(ctx *cli.Context) error {
 	}
 
 	resp, err := client.ListUtxos(ctxc, &taprpc.ListUtxosRequest{
-		IncludeLeased: ctx.Bool(assetShowLeasedName),
-		ScriptKeyType: scriptKeyQuery,
+		IncludeLeased:  ctx.Bool(assetShowLeasedName),
+		ScriptKeyType:  scriptKeyQuery,
+		IncludeChannel: ctx.Bool(includeChannelName),
 	})
 	if err != nil {
 		return fmt.Errorf("unable to list utxos: %w", err)
@@ -946,8 +966,8 @@ func listUtxos(ctx *cli.Context) error {
 var listGroupsCommand = cli.Command{
 	Name:        "groups",
 	ShortName:   "g",
-	Usage:       "list all asset groups",
-	Description: "list all asset groups known to the daemon",
+	Usage:       "list asset groups",
+	Description: "list asset groups known to the daemon",
 	Action:      listGroups,
 }
 
@@ -1003,6 +1023,16 @@ var listAssetBalancesCommand = cli.Command{
 				"key type; cannot be used at the same time " +
 				"as --" + scriptKeyTypeName,
 		},
+		cli.BoolFlag{
+			Name: includeChannelName,
+			Usage: "include assets used for funding " +
+				"custom channels in the balances",
+		},
+		cli.BoolFlag{
+			Name: includePendingName,
+			Usage: "include pending (unconfirmed) " +
+				"balances from outbound transfers",
+		},
 	},
 }
 
@@ -1017,8 +1047,10 @@ func listAssetBalances(ctx *cli.Context) error {
 	}
 
 	req := &taprpc.ListBalancesRequest{
-		IncludeLeased: ctx.Bool(assetIncludeLeasedName),
-		ScriptKeyType: scriptKeyQuery,
+		IncludeLeased:  ctx.Bool(assetIncludeLeasedName),
+		ScriptKeyType:  scriptKeyQuery,
+		IncludeChannel: ctx.Bool(includeChannelName),
+		IncludePending: ctx.Bool(includePendingName),
 	}
 
 	if !ctx.Bool(groupByGroupName) {

docs/release-notes/release-notes-0.9.0.md

@@ -0,0 +1,76 @@
+# Release Notes
+- [Bug Fixes](#bug-fixes)
+- [New Features](#new-features)
+    - [Functional Enhancements](#functional-enhancements)
+    - [RPC Additions](#rpc-additions)
+    - [tapcli Additions](#tapcli-additions)
+- [Improvements](#improvements)
+    - [Functional Updates](#functional-updates)
+    - [RPC Updates](#rpc-updates)
+    - [tapcli Updates](#tapcli-updates)
+    - [Config Changes](#config-changes)
+    - [Breaking Changes](#breaking-changes)
+    - [Performance Improvements](#performance-improvements)
+    - [Deprecations](#deprecations)
+- [Technical and Architectural Updates](#technical-and-architectural-updates)
+    - [BIP/bLIP Spec Updates](#bipblip-spec-updates)
+    - [Testing](#testing)
+    - [Database](#database)
+    - [Code Health](#code-health)
+    - [Tooling and Documentation](#tooling-and-documentation)
+
+# Bug Fixes
+
+# New Features
+
+## Functional Enhancements
+
+## RPC Additions
+
+## tapcli Additions
+
+# Improvements
+
+## Functional Updates
+
+## RPC Updates
+
+* [PR#2094](https://github.com/lightninglabs/taproot-assets/pull/2094)
+  The asset listing and balance RPCs (`ListBalances`, `ListAssets`,
+  `ListUtxos`) can now show two categories of previously-hidden
+  assets via opt-in flags. `--include_channel` surfaces assets
+  locked in Lightning channels, including both open and
+  pending-close (force-close) channel balances. `--include_pending`
+  surfaces unconfirmed outbound transfer balances and pending
+  transfer outputs, removing the need to manually filter
+  `ListTransfers` for unconfirmed entries. All new fields are
+  backward-compatible and empty by default.
+
+## tapcli Updates
+
+* [PR#2094](https://github.com/lightninglabs/taproot-assets/pull/2094)
+  Add `--include_channel` and `--include_pending` flags to
+  `tapcli assets list`, `tapcli assets balance`, and (channel
+  only) `tapcli assets utxos`.
+
+## Config Changes
+
+## Breaking Changes
+
+## Performance Improvements
+
+## Deprecations
+
+# Technical and Architectural Updates
+
+## BIP/bLIP Spec Updates
+
+## Testing
+
+## Database
+
+## Code Health
+
+## Tooling and Documentation
+
+# Contributors (Alphabetical Order)

itest/assets_test.go

@@ -663,6 +663,20 @@ func testAssetBalances(t *harnessTest) {
 	// them all.
 	AssertMintedAssetBalances(t.t, t.tapd, rpcSimpleAssets, nil, false)
 
+	// Verify that the include_pending and include_channel flags work
+	// correctly when there are no pending transfers or channels.
+	balResp, err := t.tapd.ListBalances(
+		ctx, &taprpc.ListBalancesRequest{
+			GroupBy:        groupBalancesByAssetID,
+			IncludePending: true,
+			IncludeChannel: true,
+		},
+	)
+	require.NoError(t.t, err)
+	require.NotNil(t.t, balResp)
+	require.Empty(t.t, balResp.PendingAssetBalances)
+	require.Empty(t.t, balResp.ChannelAssetBalances)
+
 	// Check chain anchor for the target asset.
 	out, err := wire.NewOutPointFromString(
 		targetAsset.ChainAnchor.AnchorOutpoint,

itest/send_test.go

@@ -100,6 +100,22 @@ func testBasicSendUnidirectional(t *harnessTest) {
 
 		sendResp, sendEvents := sendAssetsToAddr(t, t.tapd, bobAddr)
 
+		// Between broadcast and confirmation the sender should
+		// have a pending balance for the change output.
+		balResp, err := t.tapd.ListBalances(
+			ctxb, &taprpc.ListBalancesRequest{
+				GroupBy:        groupBalancesByAssetID,
+				IncludePending: true,
+			},
+		)
+		require.NoError(t.t, err)
+		require.NotEmpty(t.t, balResp.PendingAssetBalances)
+
+		assetIDHex := hex.EncodeToString(genInfo.AssetId)
+		pendingBal, ok := balResp.PendingAssetBalances[assetIDHex]
+		require.True(t.t, ok)
+		require.Equal(t.t, currentUnits, pendingBal.Balance)
+
 		ConfirmAndAssertOutboundTransfer(
 			t.t, t.lndHarness.Miner(), t.tapd, sendResp,
 			genInfo.AssetId,