Documentation
¶
Index ¶
- func DecodedLogs[T any](logs []models.Log) ([]models.TypedLog[T], error)
- func DecodedLogsWithFilter[T any](logs []models.Log, filter func(T) bool) ([]models.TypedLog[T], error)
- func FormatCursor(addr *address.Address, msgLT uint64) string
- func MatchBit(expected bool) bocBitScanner
- func MatchBits(value []byte) bocBitScanner
- func MatchBytes(sizeInBytes uint64, conditions ...Condition) bocByteScanner
- func NewQueryBuilder(store LogStore) *queryBuilder
- func NewTimestampSort(direction commonquery.SortDirection) commonquery.SortBy
- func NewTxLTSort(direction commonquery.SortDirection) commonquery.SortBy
- func ParseCursor(cursor string) (addr *address.Address, msgLT uint64, err error)
- func SkipBits(bits uint64) bocBitScanner
- func SkipBytes(bytes uint64) bocByteScanner
- type BitFilter
- type Builder
- type ByteFilter
- type Condition
- type FieldFilter
- type FieldSort
- type LogQuery
- type LogStore
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodedLogs ¶
DecodedLogs is a package-level helper that decodes raw logs into typed events using TLB. This is a convenience function for clients that want TLB parsing without coupling the logpoller to business logic.
Note: this is post-processing helper after store-level query, this affects performance since it's in-memory operation we may consider creating TypedQueryBuilder that will return TypedLog instead of Log, but that abstracts out the in-memory operation which should be visible from client, so here chosen option is: client is responsible to decode and filter the logs in memory
func DecodedLogsWithFilter ¶
func DecodedLogsWithFilter[T any](logs []models.Log, filter func(T) bool) ([]models.TypedLog[T], error)
DecodedLogsWithFilter is a package-level helper that decodes and filters raw logs using TLB. This combines decoding with application-level filtering for convenience.
func MatchBit ¶
func MatchBit(expected bool) bocBitScanner
MatchBit creates a BocBitScanner that filters a single bit at the current cursor position.
func MatchBits ¶
func MatchBits(value []byte) bocBitScanner
MatchBits creates a BocBitScanner that filters multiple bits at the current cursor position. The bit length is inferred from the value length (len(value) * 8).
func MatchBytes ¶
MatchBytes creates a BocByteScanner that applies conditions to the specified number of bytes.
func NewQueryBuilder ¶
func NewQueryBuilder(store LogStore) *queryBuilder
NewQueryBuilder creates a new query builder with the given store. This is the entry point for creating queries through the logpoller service.
func NewTimestampSort ¶
func NewTimestampSort(direction commonquery.SortDirection) commonquery.SortBy
NewTimestampSort creates a sort by transaction timestamp.
func NewTxLTSort ¶
func NewTxLTSort(direction commonquery.SortDirection) commonquery.SortBy
NewTxLTSort creates a sort by transaction logical time (tx_lt).
func ParseCursor ¶
ParseCursor parses a cursor string into its components: address, msgLT.
Types ¶
type BitFilter ¶
BitFilter represents a filter that operates on bit-level data within a log's cell. It can handle both single bits and bit ranges.
type Builder ¶
type Builder interface {
// WithSource sets the TON contract address to filter logs by (required for Execute)
WithSource(addr *address.Address) *queryBuilder
// WithEventSig sets the event signature (topic or opcode) to filter logs by (required for Execute)
WithEventSig(sig uint32) *queryBuilder
// WithFields adds field filters to the query (timestamp, block number, etc.)
WithFields(filters ...*FieldFilter) *queryBuilder
// WithBocBytes applies sequential byte-level filtering to the log's BOC data field
WithBocBytes(scanners ...bocByteScanner) *queryBuilder
// WithBocBits applies bit-level filtering to the log's BOC data field
WithBocBits(scanners ...bocBitScanner) *queryBuilder
// WithLimitAndSort sets the pagination and sorting options using chainlink-common standards
WithLimitAndSort(limitAndSort commonquery.LimitAndSort) *queryBuilder
// Execute runs the constructed query and returns filtered logs with pagination info.
// Returns error if required filters (address, event_sig) are missing.
Execute(ctx context.Context) (logs []models.Log, hasMore bool, nextCursor string, err error)
// Query returns the constructed LogQuery for inspection or custom execution
Query() *LogQuery
}
Builder defines the interface for constructing and executing log queries.
type ByteFilter ¶
ByteFilter represents a filter that operates on raw byte data within a log's cell. It filters by extracting a slice of bytes at a specific offset and applying conditions.
type Condition ¶
type Condition struct {
Operator primitives.ComparisonOperator
Value []byte
}
TODO(@jadepark-dev): probably we can merge this with normal field filter Condition represents a single comparison to be applied to a slice of bytes.
func WithCondition ¶
func WithCondition(value []byte, op primitives.ComparisonOperator) Condition
WithCondition creates a Condition for byte comparison with the given operator.
type FieldFilter ¶
type FieldFilter struct {
Field string
Operator primitives.ComparisonOperator
Value interface{}
}
FieldFilter represents a filter on a root-level field (e.g., tx_timestamp, tx_lt). This type is exported for store implementations but should not be used directly by users. Use helper functions like Timestamp() instead.
func Timestamp ¶
func Timestamp(ts time.Time, op primitives.ComparisonOperator) *FieldFilter
Timestamp creates a FieldFilter for the tx_timestamp field.
type FieldSort ¶
type FieldSort struct {
// contains filtered or unexported fields
}
FieldSort provides a flexible way to sort by any database field. The comparison logic is provided at construction time, eliminating runtime switching.
func (*FieldSort) Compare ¶
Compare compares two logs using the pre-configured comparison function. Returns negative if log1 < log2, zero if log1 == log2, positive if log1 > log2.
func (*FieldSort) GetDirection ¶
func (s *FieldSort) GetDirection() commonquery.SortDirection
GetDirection returns the sort direction for this field sort.
type LogQuery ¶
type LogQuery struct {
FieldFilters []*FieldFilter
ByteFilters []*ByteFilter
BitFilters []*BitFilter
LimitAndSort commonquery.LimitAndSort
}
LogQuery represents a complete query structure that can be passed to stores
type LogStore ¶
type LogStore interface {
QueryLogs(ctx context.Context, query *LogQuery) (logs []models.Log, hasMore bool, nextCursor string, err error)
}
LogStore defines the minimal interface needed by QueryBuilder to retrieve filtered logs. This avoids circular import by defining only what QueryBuilder needs.
Source Files