logpoller

type Config struct {
	PollPeriod                time.Duration
	PageSize                  uint32
	LogPollerStartingLookback time.Duration
	BlockTime                 time.Duration
}

type FilterStore interface {
	// RegisterFilter adds a new filter or overwrites an existing one with the same name.
	RegisterFilter(ctx context.Context, flt types.Filter) error
	// UnregisterFilter removes a filter by its unique name.
	UnregisterFilter(ctx context.Context, name string) error
	// HasFilter checks if a filter with the given name exists.
	HasFilter(ctx context.Context, name string) (bool, error)
	// GetDistinctAddresses returns a slice of unique addresses that are being monitored.
	GetDistinctAddresses(ctx context.Context) ([]*address.Address, error)
	// GetFiltersForAddressAndMsgType returns filters for a specific address and message type.
	GetFiltersForAddressAndMsgType(ctx context.Context, addr *address.Address, msgType tlb.MsgType) ([]types.Filter, error)
}

type LogStore interface {
	SaveLog(log types.Log)
	// GetLogs retrieves raw logs for a given address and event signature without any parsing or filtering.
	// This is a simple method that returns the raw cell data for further processing.
	GetLogs(srcAddr *address.Address, sig uint32) ([]types.Log, error)
}

type QueryBuilder[T any] interface {
	// WithSource sets the TON contract address to filter logs by.
	WithSource(addr *address.Address) QueryBuilder[T]

	// WithEventSig sets the event signature (topic or opcode) to filter logs by.
	WithEventSig(sig uint32) QueryBuilder[T]

	// SkipBytes advances the internal byte cursor, ignoring a specified number of bytes.
	SkipBytes(bytes uint) QueryBuilder[T]

	// FilterBytes applies conditions to the next `sizeInBytes` at the current cursor position,
	// then advances the cursor.
	FilterBytes(sizeInBytes uint, conditions ...query.Condition) QueryBuilder[T]

	// FilterTyped adds a high-level filter function that operates on the parsed event data.
	FilterTyped(filter func(T) bool) QueryBuilder[T]

	// Limit sets the maximum number of results to return.
	Limit(limit int) QueryBuilder[T]

	// Offset sets the number of results to skip from the beginning.
	Offset(offset int) QueryBuilder[T]

	// OrderBy specifies the sorting order for the results.
	OrderBy(field query.SortField, order query.SortOrder) QueryBuilder[T]

	// Execute runs the constructed query and returns the results.
	Execute(ctx context.Context, store LogStore) (query.Result[T], error)
}

type Service interface {
	services.Service
	RegisterFilter(ctx context.Context, flt types.Filter) error
	UnregisterFilter(ctx context.Context, name string) error
	HasFilter(ctx context.Context, name string) (bool, error)
	GetStore() LogStore
	Replay(ctx context.Context, fromBlock uint32) error
}

type ServiceOptions struct {
	Config   Config
	Client   ton.APIClientWrapped
	Filters  FilterStore
	TxLoader TxLoader
	TxParser TxParser
	Store    LogStore
}

type TxLoader interface {
	// LoadTxsForAddresses retrieves all transactions from the specified source addresses
	// within the given block range (prevBlock, toBlock] - exclusive of prevBlock, inclusive of toBlock.
	LoadTxsForAddresses(ctx context.Context, blockRange *types.BlockRange, srcAddrs []*address.Address) ([]types.TxWithBlock, error)
}

type TxParser interface {
	// It processes transactions by examining their messages, applying registered filters, and extracting
	// relevant event data. The parser handles different message types (internal, external out) and
	// extracts event signatures (opcodes for internal messages, topics for external out messages)
	// along with the message body data to create structured log entries.
	ParseTransactions(ctx context.Context, txs []types.TxWithBlock) ([]types.Log, error)
}