tapdb: switch proof cache to size-based limits and add deep size estimation

.github/workflows/main.yaml

@@ -4,12 +4,14 @@ on:
   push:
     branches:
       - 'main'
+      - '*-staging'
   pull_request:
     branches:
       - '*'
   merge_group:
     branches:
       - 'main'
+      - '*-staging'
 
 defaults:
   run:

address/event.go

@@ -41,6 +41,33 @@ const (
 	StatusCompleted Status = 3
 )
 
+// SortDirection is an enum used to specify the order of returned events.
+type SortDirection uint8
+
+const (
+	// UndefinedSortDirection indicates that the sort direction
+	// is not specified.
+	UndefinedSortDirection SortDirection = iota
+
+	// DescSortDirection indicates that the sort should be in
+	// descending order.
+	DescSortDirection
+
+	// AscSortDirection indicates that the sort should be in
+	// ascending order.
+	AscSortDirection
+)
+
+const (
+	// DefaultEventQueryLimit is the number of events returned
+	// when no limit is provided.
+	DefaultEventQueryLimit = 512
+
+	// MaxEventQueryLimit is the maximum number of events that can be
+	// returned in a single query.
+	MaxEventQueryLimit = 16384
+)
+
 // EventQueryParams holds the set of query params for address events.
 type EventQueryParams struct {
 	// AddrTaprootOutputKey is the optional 32-byte x-only serialized
@@ -65,6 +92,17 @@ type EventQueryParams struct {
 	// (inclusive). Can be set to nil to return events of all creation
 	// times.
 	CreationTimeTo *time.Time
+
+	// Offset is the offset into the result set to start returning events.
+	Offset int32
+
+	// Limit is the max number of events that should be returned. If zero,
+	// then DefaultEventQueryLimit will be used.
+	Limit int32
+
+	// SortDirection is the sort direction to use when returning the
+	// events. The default zero value sorts the events in ascending order.
+	SortDirection SortDirection
 }
 
 // AssetOutput holds the information about a single asset output that was sent

cmd/commands/addrs.go

@@ -158,6 +158,8 @@ const (
 	limitName = "limit"
 
 	offsetName = "offset"
+
+	directionName = "direction"
 )
 
 var queryAddrsCommand = cli.Command{
@@ -293,6 +295,20 @@ var receivesAddrCommand = cli.Command{
 			Usage: "filter transfers created before this + " +
 				"unix timestamp (seconds)",
 		},
+		cli.Int64Flag{
+			Name:  limitName,
+			Usage: "the max number of events returned",
+		},
+		cli.Int64Flag{
+			Name:  offsetName,
+			Usage: "the number of events to skip",
+		},
+		cli.StringFlag{
+			Name: directionName,
+			Usage: "the sort direction for events (asc or desc). " +
+				"Defaults to desc.",
+			Value: "desc",
+		},
 	},
 	Action: addrReceives,
 }
@@ -311,10 +327,18 @@ func addrReceives(ctx *cli.Context) error {
 		addr = ctx.Args().First()
 	}
 
+	direction := taprpc.SortDirection_SORT_DIRECTION_DESC
+	if ctx.String(directionName) == "asc" {
+		direction = taprpc.SortDirection_SORT_DIRECTION_ASC
+	}
+
 	resp, err := client.AddrReceives(ctxc, &taprpc.AddrReceivesRequest{
 		FilterAddr:     addr,
 		StartTimestamp: ctx.Uint64("start_timestamp"),
 		EndTimestamp:   ctx.Uint64("end_timestamp"),
+		Limit:          int32(ctx.Int64(limitName)),
+		Offset:         int32(ctx.Int64(offsetName)),
+		Direction:      direction,
 	})
 	if err != nil {
 		return fmt.Errorf("unable to query addr receives: %w", err)

cmd/commands/assets.go

@@ -8,9 +8,11 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/btcsuite/btcd/btcec/v2"
 	"github.com/btcsuite/btcd/wire"
 	taprootassets "github.com/lightninglabs/taproot-assets"
 	"github.com/lightninglabs/taproot-assets/address"
+	"github.com/lightninglabs/taproot-assets/asset"
 	"github.com/lightninglabs/taproot-assets/tapcfg"
 	"github.com/lightninglabs/taproot-assets/taprpc"
 	wrpc "github.com/lightninglabs/taproot-assets/taprpc/assetwalletrpc"
@@ -1092,6 +1094,10 @@ var burnAssetsCommand = cli.Command{
 			Name:  assetIDName,
 			Usage: "the asset ID to burn units from",
 		},
+		cli.StringFlag{
+			Name:  assetGroupKeyName,
+			Usage: "the group key to burn units from",
+		},
 		cli.Uint64Flag{
 			Name:  assetAmountName,
 			Usage: "the amount of units to burn/destroy",
@@ -1106,15 +1112,66 @@ var burnAssetsCommand = cli.Command{
 	Action: burnAssets,
 }
 
+// buildAssetSpecifier validates and constructs an asset.Specifier from
+// CLI context
+func buildAssetSpecifier(ctx *cli.Context) (*asset.Specifier, error) {
+	assetIDHex := ctx.String(assetIDName)
+	groupKeyHex := ctx.String(assetGroupKeyName)
+
+	// At least one of asset ID or group key must be provided.
+	if assetIDHex == "" && groupKeyHex == "" {
+		return nil, fmt.Errorf("either asset ID or " +
+			"group key must be specified")
+	}
+
+	var (
+		assetID  *asset.ID
+		groupKey *btcec.PublicKey
+		err      error
+	)
+
+	// Parse asset ID if provided.
+	if assetIDHex != "" {
+		assetIDBytes, err := hex.DecodeString(assetIDHex)
+		if err != nil {
+			return nil, fmt.Errorf("invalid asset ID: %w", err)
+		}
+
+		var id asset.ID
+		copy(id[:], assetIDBytes)
+		assetID = &id
+	}
+
+	// Parse group key if provided.
+	if groupKeyHex != "" {
+		groupKeyBytes, err := hex.DecodeString(groupKeyHex)
+		if err != nil {
+			return nil, fmt.Errorf("invalid group key: %w", err)
+		}
+
+		groupKey, err = btcec.ParsePubKey(groupKeyBytes)
+		if err != nil {
+			return nil, fmt.Errorf("invalid group key: %w", err)
+		}
+	}
+
+	// Construct the asset specifier.
+	assetSpecifier, err := asset.NewSpecifier(assetID, groupKey, nil, true)
+	if err != nil {
+		return nil, fmt.Errorf("invalid asset specifier: %w", err)
+	}
+
+	return &assetSpecifier, nil
+}
+
 func burnAssets(ctx *cli.Context) error {
 	if ctx.NArg() != 0 || ctx.NumFlags() == 0 {
 		return cli.ShowSubcommandHelp(ctx)
 	}
 
-	assetIDHex := ctx.String(assetIDName)
-	assetIDBytes, err := hex.DecodeString(assetIDHex)
+	assetSpecifier, err := buildAssetSpecifier(ctx)
 	if err != nil {
-		return fmt.Errorf("invalid asset ID")
+		return fmt.Errorf("invalid asset specifier: %w", err)
 	}
 
 	burnAmount := ctx.Uint64(assetAmountName)
@@ -1126,42 +1183,82 @@ func burnAssets(ctx *cli.Context) error {
 	client, cleanUp := getClient(ctx)
 	defer cleanUp()
 
+	assetIDBytes, groupKeyBytes := assetSpecifier.AsBytes()
+
 	if !ctx.Bool(burnOverrideConfirmationName) {
-		balance, err := client.ListBalances(
-			ctxc, &taprpc.ListBalancesRequest{
-				GroupBy: &taprpc.ListBalancesRequest_AssetId{
-					AssetId: true,
+		var currBalance uint64
+
+		// When both asset ID and group key are provided,
+		// prioritize asset ID for balance checking since
+		// it's more specific.
+		switch {
+		case len(assetIDBytes) > 0:
+			// nolint: lll
+			balance, err := client.ListBalances(ctxc,
+				&taprpc.ListBalancesRequest{
+					GroupBy: &taprpc.ListBalancesRequest_AssetId{
+						AssetId: true,
+					},
+					AssetFilter: assetIDBytes,
 				},
-				AssetFilter: assetIDBytes,
-			},
-		)
-		if err != nil {
-			return fmt.Errorf("unable to list current asset "+
-				"balances: %w", err)
-		}
+			)
+			if err != nil {
+				return fmt.Errorf("unable to list current "+
+					"asset balances: %w", err)
+			}
+
+			idHex := hex.EncodeToString(assetIDBytes)
+			assetBalance, ok := balance.AssetBalances[idHex]
+			if !ok {
+				return fmt.Errorf("couldn't fetch balance for "+
+					"asset ID %x", assetIDBytes)
+			}
+
+			currBalance = assetBalance.Balance
+
+		case len(groupKeyBytes) > 0:
+			// nolint: lll
+			balance, err := client.ListBalances(ctxc,
+				&taprpc.ListBalancesRequest{
+					GroupBy: &taprpc.ListBalancesRequest_GroupKey{
+						GroupKey: true,
+					},
+					AssetFilter: groupKeyBytes,
+				},
+			)
+			if err != nil {
+				return fmt.Errorf("unable to list current "+
+					"asset balances: %w", err)
+			}
 
-		assetBalance, ok := balance.AssetBalances[assetIDHex]
-		if !ok {
-			return fmt.Errorf("couldn't fetch balance for asset %x",
-				assetIDBytes)
+			gkHex := hex.EncodeToString(groupKeyBytes)
+			groupBalance, ok := balance.AssetGroupBalances[gkHex]
+			if !ok {
+				return fmt.Errorf("couldn't fetch balance for "+
+					"group key %x", groupKeyBytes)
+			}
+
+			currBalance = groupBalance.Balance
 		}
 
 		msg := fmt.Sprintf("Please confirm destructive action.\n"+
-			"Asset ID: %x\nCurrent available balance: %d\n"+
+			"%s\nCurrent available balance: %d\n"+
 			"Amount to burn: %d\n Are you sure you want to "+
 			"irreversibly burn (destroy, remove from circulation) "+
 			"the specified amount of assets?\nPlease answer 'yes' "+
-			"or 'no' and press enter: ", assetIDBytes,
-			assetBalance.Balance, burnAmount)
+			"or 'no' and press enter: ",
+			assetSpecifier.String(), currBalance, burnAmount,
+		)
 
 		if !promptForConfirmation(msg) {
 			return nil
 		}
 	}
 
 	resp, err := client.BurnAsset(ctxc, &taprpc.BurnAssetRequest{
-		Asset: &taprpc.BurnAssetRequest_AssetId{
-			AssetId: assetIDBytes,
+		AssetSpecifier: &taprpc.AssetSpecifier{
+			Id:       assetIDBytes,
+			GroupKey: groupKeyBytes,
 		},
 		AmountToBurn:     burnAmount,
 		ConfirmationText: taprootassets.AssetBurnConfirmationText,

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

@@ -218,6 +218,9 @@
   information directly from the RPC response without performing separate
   blockchain queries.
 
+- The `AddrReceives` RPC has new fields `limit`, `offset` and `direction` that
+  allows pagination and sorting. [See PR](https://github.com/lightninglabs/taproot-assets/pull/1813).
+
 ## tapcli Additions
 
 - [Rename](https://github.com/lightninglabs/taproot-assets/pull/1682) the mint
@@ -239,6 +242,9 @@
 - The `tapcli addrs receives` command now supports 
   [new `--start_timestamp` and `--end_timestamp` flags](https://github.com/lightninglabs/taproot-assets/pull/1794).
 
+- The `tapcli addrs receives` command now has new flags `--limit`, `--offset` and
+  `--direction` that allows pagination and sorting. [See PR](https://github.com/lightninglabs/taproot-assets/pull/1813).
+
 - The `fetchsupplycommit` command [now supports](https://github.com/lightninglabs/taproot-assets/pull/1823)
   a `--first` flag to fetch the very first supply commitment; if no flag is
   provided, it defaults to fetching the latest. Only one of `--first`,