Merge pull request #1813 from lightninglabs/feat/addr-receives-pagination

`AddrReceives` pagination and sorting direction.

Author: darioAnongba

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)

docs/asset-channel-funding.md

@@ -78,6 +78,7 @@
    - https://github.com/lightninglabs/taproot-assets/pull/1797
    - https://github.com/lightninglabs/taproot-assets/pull/1823
    - https://github.com/lightninglabs/taproot-assets/pull/1822
+   - https://github.com/lightninglabs/taproot-assets/pull/1820
 
 - A new [address version 2 was introduced that supports grouped assets and
   custom (sender-defined)
@@ -173,6 +174,9 @@
 - The `AddrReceives` RPC now supports timestamp filtering with
   [new `StartTimestamp` and `EndTimestamp` fields](https://github.com/lightninglabs/taproot-assets/pull/1794).
 
+- 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
@@ -194,6 +198,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`,