time range for transactions

Author: nischitpra

README.md

@@ -461,4 +461,63 @@ storage:
       host: localhost
       username: admin
       password: password
-```
+```
+
+## API Documentation
+
+### Transaction Queries with Time Range Filtering
+
+The transaction endpoints support time-based filtering using Unix timestamps. This allows you to query transactions within a specific time range.
+
+#### Time Range Parameters
+
+- `from_time` (optional): Start time for filtering (Unix timestamp)
+- `to_time` (optional): End time for filtering (Unix timestamp, defaults to current time)
+
+#### Configuration
+
+The maximum allowed time range is configurable via the `api.transactionMaxTimeRangeSeconds` setting:
+
+```yaml
+api:
+  host: ":8080"
+  transactionMaxTimeRangeSeconds: 604800  # 1 week in seconds (default)
+```
+
+#### Examples
+
+**Query transactions from a specific time to now:**
+```
+GET /{chainId}/transactions?from_time=1640995200
+```
+
+**Query transactions within a specific time range:**
+```
+GET /{chainId}/transactions?from_time=1640995200&to_time=1641081600
+```
+
+**Query wallet transactions with time filtering:**
+```
+GET /{chainId}/wallet-transactions/{wallet_address}?from_time=1640995200&to_time=1641081600
+```
+
+#### Validation Rules
+
+1. If `to_time` is not provided, it defaults to the current time
+2. The time range (`to_time - from_time`) cannot exceed the configured `maxTimeRangeSeconds`
+3. `from_time` must be less than `to_time`
+4. Both parameters are optional, but if provided, they must be valid Unix timestamps
+
+#### Error Responses
+
+- `400 Bad Request`: If the time range exceeds the maximum allowed duration
+- `400 Bad Request`: If `from_time` is greater than or equal to `to_time`
+- `400 Bad Request`: If timestamps are invalid
+
+#### Supported Endpoints
+
+Time range filtering is available on all transaction endpoints:
+- `GET /{chainId}/transactions`
+- `GET /{chainId}/wallet-transactions/{wallet_address}`
+- `GET /{chainId}/transactions/{to}`
+- `GET /{chainId}/transactions/{to}/{signature}`

api/api.go

@@ -46,6 +46,10 @@ type QueryParams struct {
 	Decode bool `schema:"decode"`
 	// @Description Flag to force consistent data at the expense of query speed
 	ForceConsistentData bool `schema:"force_consistent_data"`
+	// @Description Start time for filtering (Unix timestamp)
+	FromTime int64 `schema:"from_time"`
+	// @Description End time for filtering (Unix timestamp)
+	ToTime int64 `schema:"to_time"`
 }
 
 // Meta represents metadata for a query response

configs/config.example.yml

@@ -41,6 +41,10 @@ reorgHandler:
 validation:
   mode: strict  # "disabled", "minimal", or "strict"
 
+api:
+  host: ":8080"
+  transactionMaxTimeRangeSeconds: 604800  # 1 week in seconds
+
 storage:
   main:
     clickhouse:

configs/config.go

@@ -124,12 +124,13 @@ type ContractApiRequestConfig struct {
 }
 
 type APIConfig struct {
-	Host                string                   `mapstructure:"host"`
-	BasicAuth           BasicAuthConfig          `mapstructure:"basicAuth"`
-	ThirdwebContractApi string                   `mapstructure:"thirdwebContractApi"`
-	ContractApiRequest  ContractApiRequestConfig `mapstructure:"contractApiRequest"`
-	AbiDecodingEnabled  bool                     `mapstructure:"abiDecodingEnabled"`
-	Thirdweb            ThirdwebConfig           `mapstructure:"thirdweb"`
+	Host                           string                   `mapstructure:"host"`
+	BasicAuth                      BasicAuthConfig          `mapstructure:"basicAuth"`
+	ThirdwebContractApi            string                   `mapstructure:"thirdwebContractApi"`
+	ContractApiRequest             ContractApiRequestConfig `mapstructure:"contractApiRequest"`
+	AbiDecodingEnabled             bool                     `mapstructure:"abiDecodingEnabled"`
+	Thirdweb                       ThirdwebConfig           `mapstructure:"thirdweb"`
+	TransactionMaxTimeRangeSeconds int                      `mapstructure:"transactionMaxTimeRangeSeconds"`
 }
 
 type BlockPublisherConfig struct {

internal/handlers/transactions_handlers.go

@@ -1,7 +1,9 @@
 package handlers
 
 import (
+	"fmt"
 	"net/http"
+	"time"
 
 	"github.com/ethereum/go-ethereum/accounts/abi"
 	gethCommon "github.com/ethereum/go-ethereum/common"
@@ -28,6 +30,8 @@ import (
 // @Param limit query int false "Number of items per page" default(5)
 // @Param aggregate query []string false "List of aggregate functions to apply"
 // @Param force_consistent_data query bool false "Force consistent data at the expense of query speed"
+// @Param from_time query int false "Start time for filtering (Unix timestamp)"
+// @Param to_time query int false "End time for filtering (Unix timestamp, defaults to current time)"
 // @Success 200 {object} api.QueryResponse{data=[]common.TransactionModel}
 // @Failure 400 {object} api.Error
 // @Failure 401 {object} api.Error
@@ -53,6 +57,8 @@ func GetTransactions(c *gin.Context) {
 // @Param limit query int false "Number of items per page" default(5)
 // @Param force_consistent_data query bool false "Force consistent data at the expense of query speed"
 // @Param decode query bool false "Decode transaction data"
+// @Param from_time query int false "Start time for filtering (Unix timestamp)"
+// @Param to_time query int false "End time for filtering (Unix timestamp, defaults to current time)"
 // @Success 200 {object} api.QueryResponse{data=[]common.DecodedTransactionModel}
 // @Failure 400 {object} api.Error
 // @Failure 401 {object} api.Error
@@ -78,6 +84,8 @@ func GetWalletTransactions(c *gin.Context) {
 // @Param limit query int false "Number of items per page" default(5)
 // @Param aggregate query []string false "List of aggregate functions to apply"
 // @Param force_consistent_data query bool false "Force consistent data at the expense of query speed"
+// @Param from_time query int false "Start time for filtering (Unix timestamp)"
+// @Param to_time query int false "End time for filtering (Unix timestamp, defaults to current time)"
 // @Success 200 {object} api.QueryResponse{data=[]common.TransactionModel}
 // @Failure 400 {object} api.Error
 // @Failure 401 {object} api.Error
@@ -104,6 +112,8 @@ func GetTransactionsByContract(c *gin.Context) {
 // @Param limit query int false "Number of items per page" default(5)
 // @Param aggregate query []string false "List of aggregate functions to apply"
 // @Param force_consistent_data query bool false "Force consistent data at the expense of query speed"
+// @Param from_time query int false "Start time for filtering (Unix timestamp)"
+// @Param to_time query int false "End time for filtering (Unix timestamp, defaults to current time)"
 // @Success 200 {object} api.QueryResponse{data=[]common.DecodedTransactionModel}
 // @Failure 400 {object} api.Error
 // @Failure 401 {object} api.Error
@@ -129,6 +139,35 @@ func handleTransactionsRequest(c *gin.Context) {
 		return
 	}
 
+	// Parse and validate time parameters
+	fromTime := queryParams.FromTime
+	toTime := queryParams.ToTime
+
+	// If toTime is not provided, default to current time
+	if toTime == 0 {
+		toTime = time.Now().Unix()
+	}
+
+	// Validate time range
+	if fromTime > 0 && toTime > 0 {
+		timeRange := toTime - fromTime
+		maxTimeRange := int64(config.Cfg.API.TransactionMaxTimeRangeSeconds)
+		if maxTimeRange == 0 {
+			// Default to 1 week if not configured
+			maxTimeRange = 7 * 24 * 60 * 60 // 1 week in seconds
+		}
+
+		if timeRange > maxTimeRange {
+			api.BadRequestErrorHandler(c, fmt.Errorf("time range cannot exceed %d seconds (approximately %d days)", maxTimeRange, maxTimeRange/(24*60*60)))
+			return
+		}
+
+		if fromTime >= toTime {
+			api.BadRequestErrorHandler(c, fmt.Errorf("from_time must be less than to_time"))
+			return
+		}
+	}
+
 	var functionABI *abi.Method
 	signatureHash := ""
 	if signature != "" {
@@ -158,6 +197,8 @@ func handleTransactionsRequest(c *gin.Context) {
 		Page:                queryParams.Page,
 		Limit:               queryParams.Limit,
 		ForceConsistentData: queryParams.ForceConsistentData,
+		FromTime:            fromTime,
+		ToTime:              toTime,
 	}
 
 	// Initialize the QueryResult

internal/storage/clickhouse.go

@@ -500,6 +500,10 @@ func (c *ClickHouseConnector) GetAggregations(table string, qf QueryFilter) (Que
 	if signatureClause != "" {
 		whereClauses = append(whereClauses, signatureClause)
 	}
+	timeRangeClause := createTimeRangeClause(qf.FromTime, qf.ToTime)
+	if timeRangeClause != "" {
+		whereClauses = append(whereClauses, timeRangeClause)
+	}
 	for key, value := range qf.FilterParams {
 		whereClauses = append(whereClauses, createFilterClause(key, strings.ToLower(value)))
 	}
@@ -641,6 +645,10 @@ func (c *ClickHouseConnector) buildQuery(table, columns string, qf QueryFilter)
 	if signatureClause != "" {
 		whereClauses = append(whereClauses, signatureClause)
 	}
+	timeRangeClause := createTimeRangeClause(qf.FromTime, qf.ToTime)
+	if timeRangeClause != "" {
+		whereClauses = append(whereClauses, timeRangeClause)
+	}
 	// Add filter params
 	for key, value := range qf.FilterParams {
 		whereClauses = append(whereClauses, createFilterClause(key, strings.ToLower(value)))
@@ -749,6 +757,24 @@ func createSignatureClause(table, signature string) string {
 	return ""
 }
 
+func createTimeRangeClause(fromTime, toTime int64) string {
+	clauses := []string{}
+
+	if fromTime > 0 {
+		clauses = append(clauses, fmt.Sprintf("block_timestamp >= toDateTime(%d)", fromTime))
+	}
+
+	if toTime > 0 {
+		clauses = append(clauses, fmt.Sprintf("block_timestamp <= toDateTime(%d)", toTime))
+	}
+
+	if len(clauses) == 0 {
+		return ""
+	}
+
+	return strings.Join(clauses, " AND ")
+}
+
 func getTopicValueFormat(topic string) string {
 	if topic == "" {
 		// if there is no indexed topic, indexer stores an empty string

internal/storage/clickhouse_connector_test.go

@@ -132,3 +132,47 @@ func TestMapClickHouseTypeToGoType(t *testing.T) {
 		})
 	}
 }
+
+// TestCreateTimeRangeClause tests the createTimeRangeClause function
+func TestCreateTimeRangeClause(t *testing.T) {
+	testCases := []struct {
+		name     string
+		fromTime int64
+		toTime   int64
+		expected string
+	}{
+		{
+			name:     "both times provided",
+			fromTime: 1640995200, // 2022-01-01 00:00:00 UTC
+			toTime:   1641081600, // 2022-01-02 00:00:00 UTC
+			expected: "block_timestamp >= toDateTime(1640995200) AND block_timestamp <= toDateTime(1641081600)",
+		},
+		{
+			name:     "only from time",
+			fromTime: 1640995200,
+			toTime:   0,
+			expected: "block_timestamp >= toDateTime(1640995200)",
+		},
+		{
+			name:     "only to time",
+			fromTime: 0,
+			toTime:   1641081600,
+			expected: "block_timestamp <= toDateTime(1641081600)",
+		},
+		{
+			name:     "no times provided",
+			fromTime: 0,
+			toTime:   0,
+			expected: "",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			result := createTimeRangeClause(tc.fromTime, tc.toTime)
+			if result != tc.expected {
+				t.Errorf("createTimeRangeClause(%d, %d) = %s, want %s", tc.fromTime, tc.toTime, result, tc.expected)
+			}
+		})
+	}
+}

internal/storage/connector.go

@@ -24,6 +24,8 @@ type QueryFilter struct {
 	WalletAddress       string
 	Signature           string
 	ForceConsistentData bool
+	FromTime            int64
+	ToTime              int64
 }
 
 type TransfersQueryFilter struct {