tapdb: add pagination and ordering to QueryAddrEvents

Author: darioAnongba

address/event.go

@@ -41,6 +41,28 @@ const (
 	StatusCompleted Status = 3
 )
 
+// SortDirection is an enum used to specify the order of returned events.
+type SortDirection uint8
+
+const (
+	// SortAscending is a sentinel value that indicates that the sort
+	// should be in ascending order.
+	SortAscending SortDirection = iota
+
+	// SortDescending is a sentinel value that indicates that the sort
+	// should be in descending order.
+	SortDescending
+)
+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
@@ -60,6 +82,17 @@ type EventQueryParams struct {
 	// (inclusive). Can be set to nil to return events of all creation
 	// times.
 	CreationTimeFrom *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

rpcserver.go

@@ -2230,6 +2230,10 @@ func (r *rpcServer) AddrReceives(ctx context.Context,
 	if req.Limit < 0 {
 		return nil, fmt.Errorf("limit must be non-negative")
 	}
+	if req.Limit > address.MaxEventQueryLimit {
+		return nil, fmt.Errorf("limit must be less than %d",
+			address.MaxEventQueryLimit)
+	}
 
 	sqlQuery.Offset = req.Offset
 	sqlQuery.Limit = req.Limit

tapdb/addrs.go

@@ -990,9 +990,12 @@ func (t *TapAddressBook) QueryAddrEvents(
 	error) {
 
 	sqlQuery := AddrEventQuery{
-		StatusFrom:   int16(address.StatusTransactionDetected),
-		StatusTo:     int16(address.StatusCompleted),
-		CreatedAfter: time.Unix(0, 0).UTC(),
+		StatusFrom:    int16(address.StatusTransactionDetected),
+		StatusTo:      int16(address.StatusCompleted),
+		CreatedAfter:  time.Unix(0, 0).UTC(),
+		NumLimit:      params.Limit,
+		NumOffset:     params.Offset,
+		SortDirection: sqlInt16(params.SortDirection),
 	}
 	if len(params.AddrTaprootOutputKey) > 0 {
 		sqlQuery.AddrTaprootKey = params.AddrTaprootOutputKey
@@ -1006,6 +1009,9 @@ func (t *TapAddressBook) QueryAddrEvents(
 	if params.CreationTimeFrom != nil && !params.CreationTimeFrom.IsZero() {
 		sqlQuery.CreatedAfter = params.CreationTimeFrom.UTC()
 	}
+	if params.Limit == 0 {
+		sqlQuery.NumLimit = int32(address.DefaultEventQueryLimit)
+	}
 
 	var (
 		readTxOpts = NewAssetStoreReadTx()

tapdb/addrs_test.go

@@ -935,6 +935,97 @@ func TestQueryAddrEvents(t *testing.T) {
 	require.Equal(t, event.Outpoint, events[0].Outpoint)
 }
 
+// TestQueryAddrEventsPagination tests that query parameters for pagination are
+// applied when listing address events.
+func TestQueryAddrEventsPagination(t *testing.T) {
+	t.Parallel()
+
+	// First, make a new addr book instance we'll use in the test below.
+	testClock := clock.NewTestClock(time.Now())
+	addrBook, _ := newAddrBook(t, testClock)
+
+	ctx := context.Background()
+
+	// Insert a test address.
+	addrVersion := test.RandFlip(address.V0, address.V1)
+	proofCourierAddr := address.RandProofCourierAddrForVersion(
+		t, addrVersion,
+	)
+	addr, assetGen, assetGroup := address.RandAddrWithVersion(
+		t, chainParams, proofCourierAddr, addrVersion,
+	)
+	err := addrBook.db.ExecTx(
+		ctx, WriteTxOption(),
+		insertFullAssetGen(ctx, assetGen, assetGroup),
+	)
+	require.NoError(t, err)
+	require.NoError(t, addrBook.InsertAddrs(ctx, *addr))
+
+	// Insert events.
+	const numEvents = 5
+	events := make([]*address.Event, numEvents)
+	baseTime := testClock.Now()
+	for i := range numEvents {
+		testClock.SetTime(baseTime.Add(time.Duration(i) * time.Minute))
+		tx := randWalletTx()
+		event, err := addrBook.GetOrCreateEvent(
+			ctx, address.StatusTransactionDetected,
+			newTransfer(t, addr, tx, 0),
+		)
+		require.NoError(t, err)
+		events[i] = event
+	}
+
+	// Test all events.
+	allEvents, err := addrBook.QueryAddrEvents(
+		ctx,
+		address.EventQueryParams{},
+	)
+	require.NoError(t, err)
+	require.Len(t, allEvents, numEvents)
+
+	// Test limit.
+	firstPage, err := addrBook.QueryAddrEvents(
+		ctx,
+		address.EventQueryParams{
+			Limit:         2,
+			SortDirection: address.SortAscending,
+		},
+	)
+	require.NoError(t, err)
+	require.Len(t, firstPage, 2)
+	require.Equal(t, events[0].ID, firstPage[0].ID)
+	require.Equal(t, events[1].ID, firstPage[1].ID)
+
+	// Test offset and limit.
+	secondPage, err := addrBook.QueryAddrEvents(
+		ctx,
+		address.EventQueryParams{
+			Limit:         2,
+			Offset:        2,
+			SortDirection: address.SortAscending,
+		},
+	)
+	require.NoError(t, err)
+	require.Len(t, secondPage, 2)
+	require.Equal(t, events[2].ID, secondPage[0].ID)
+	require.Equal(t, events[3].ID, secondPage[1].ID)
+
+	// Test ordering.
+	descPage, err := addrBook.QueryAddrEvents(
+		ctx,
+		address.EventQueryParams{
+			Limit:         2,
+			Offset:        1,
+			SortDirection: address.SortDescending,
+		},
+	)
+	require.NoError(t, err)
+	require.Len(t, descPage, 2)
+	require.Equal(t, events[3].ID, descPage[0].ID)
+	require.Equal(t, events[2].ID, descPage[1].ID)
+}
+
 // TestAddrByScriptKeyAndVersion tests that we can retrieve an address by its
 // script key and version.
 func TestAddrByScriptKeyAndVersion(t *testing.T) {

tapdb/sqlc/addrs.sql.go

@@ -222,11 +222,16 @@ SELECT
 FROM addr_events
 JOIN addrs
   ON addr_events.addr_id = addrs.id
-WHERE addr_events.status >= @status_from 
+WHERE addr_events.status >= @status_from
   AND addr_events.status <= @status_to
   AND COALESCE(@addr_taproot_key, addrs.taproot_output_key) = addrs.taproot_output_key
   AND addr_events.creation_time >= @created_after
-ORDER by addr_events.creation_time;
+ORDER BY
+    CASE WHEN sqlc.narg('sort_direction') = 0 THEN addr_events.creation_time END ASC,
+    CASE WHEN sqlc.narg('sort_direction') = 1 THEN addr_events.creation_time END DESC,
+    CASE WHEN sqlc.narg('sort_direction') = 0 THEN addr_events.id END ASC,
+    CASE WHEN sqlc.narg('sort_direction') = 1 THEN addr_events.id END DESC
+LIMIT @num_limit OFFSET @num_offset;
 
 -- name: QueryLastEventHeight :one
 SELECT cast(coalesce(max(chain_txns.block_height), 0) AS BIGINT) AS last_height