eventfeed

Documentation

Index

• Constants
• Variables
• type BlockEvents
• type ChainClient
• type Config
  • func DefaultConfig() *Config
• type EVMBlockInfo
• type EVMEvent
• type EventFeed
• type EventFeedStore
• type EventType
• type Option
  • func WithChainAPIBackoff(backoff time.Duration) Option
  • func WithEventPersistence(enabled bool) Option
  • func WithFetchExtraBlockInformation(enabled bool) Option
  • func WithMinBlockDepth(depth int) Option
  • func WithNewHeadPollFreq(pollFreq time.Duration) Option
• type TxnEvents

Constants

const (
	// RunSQL is a RunSQL event fired by the SC.
	RunSQL EventType = "RunSQL"
	// CreateTable is a CreateTable event fired by the SC.
	CreateTable = "CreateTable"
	// SetController is a SetController event fired by the SC.
	SetController = "SetController"
	// TransferTable is a TransferTable event fired by the SC.
	TransferTable = "TransferTable"
)

Variables

var SupportedEvents = map[EventType]reflect.Type{
	RunSQL:        reflect.TypeOf(tbleth.ContractRunSQL{}),
	CreateTable:   reflect.TypeOf(tbleth.ContractCreateTable{}),
	SetController: reflect.TypeOf(tbleth.ContractSetController{}),
	TransferTable: reflect.TypeOf(tbleth.ContractTransferTable{}),
}

SupportedEvents contains a map from **all** EventType values to the corresponding struct that will be used for unmarshaling. Note that tbleth.Contract*** is automatically generated by `make ethereum`, so keeping this mapping is easy since these structs are generated from the contract ABI.

IMPORTANT: we should *always* have a mapping for all EventType values.

Types

type BlockEvents

type BlockEvents struct {
	BlockNumber int64
	Txns        []TxnEvents
}

BlockEvents contains a set of events for a particular block height.

type ChainClient

type ChainClient interface {
	FilterLogs(ctx context.Context, query ethereum.FilterQuery) ([]types.Log, error)
	HeaderByNumber(ctx context.Context, block *big.Int) (*types.Header, error)
}

ChainClient provides basic apis for an EventFeed.

type Config

type Config struct {
	MinBlockChainDepth  int
	ChainAPIBackoff     time.Duration
	NewHeadPollFreq     time.Duration
	PersistEvents       bool
	FetchExtraBlockInfo bool
}

Config contains configuration parameters for an event feed.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns the default configuration.

type EVMBlockInfo

type EVMBlockInfo struct {
	ChainID     tableland.ChainID
	BlockNumber int64
	Timestamp   time.Time
}

EVMBlockInfo contains information about an EVM block.

type EVMEvent

type EVMEvent struct {
	Address     common.Address
	Topics      []byte
	Data        []byte
	BlockNumber uint64
	TxHash      common.Hash
	TxIndex     uint
	BlockHash   common.Hash
	Index       uint

	// Enhanced fields
	ChainID   tableland.ChainID
	EventJSON []byte
	EventType string
}

EVMEvent is a Tableland on-chain event produced by the Registry SC.

type EventFeed

type EventFeed interface {
	Start(ctx context.Context, fromHeight int64, ch chan<- BlockEvents, filterEventTypes []EventType) error
}

EventFeed provides a stream of on-chain events from a smart contract.

type EventFeedStore

type EventFeedStore interface {
	Begin() (*sql.Tx, error)
	WithTx(*sql.Tx) EventFeedStore

	AreEVMEventsPersisted(context.Context, tableland.ChainID, common.Hash) (bool, error)
	SaveEVMEvents(context.Context, tableland.ChainID, []EVMEvent) error
	GetBlocksMissingExtraInfo(context.Context, tableland.ChainID, *int64) ([]int64, error)
	InsertBlockExtraInfo(context.Context, tableland.ChainID, int64, uint64) error
	GetEVMEvents(context.Context, tableland.ChainID, common.Hash) ([]EVMEvent, error)
	GetBlockExtraInfo(context.Context, tableland.ChainID, int64) (EVMBlockInfo, error)
}

EventFeedStore is the storage layer of EventFeed.

type EventType

type EventType string

EventType is an event type.

type Option

type Option func(*Config) error

Option modifies a configuration attribute.

func WithChainAPIBackoff

func WithChainAPIBackoff(backoff time.Duration) Option

WithChainAPIBackoff provides a sleep duration between failed node api calls to retry.

func WithEventPersistence

func WithEventPersistence(enabled bool) Option

WithEventPersistence indicates that all events should be persisted.

func WithFetchExtraBlockInformation

func WithFetchExtraBlockInformation(enabled bool) Option

WithFetchExtraBlockInformation indicates that we'll persist extra block information from persisted events.

func WithMinBlockDepth

func WithMinBlockDepth(depth int) Option

WithMinBlockDepth provides the confidence interval of block depth from which the event feed can safely assume block finality.

func WithNewHeadPollFreq

func WithNewHeadPollFreq(pollFreq time.Duration) Option

WithNewHeadPollFreq is the rate at which we poll the chain to detect new blocks. This should be configured close to the expected block time of the chain.

If set to lower, the validator is more reactive to new blocks as soon as they get miner paying an efficiency cost. For example, Ethereum has an expected block time of 12s. If we set this value to 6s, on average half of the polls will detect a new block.

If set to greater, the validator will have some delay to execute new events on new blocks. But, it would be more efficient in Ethereum node APIs usage, since the next detected block might be N (N>1) blocks further than the last detected one, making the `eth_getLogs(...)` query block range wider. This means that with less Ethereum node APIs we would detect more events on average (again, paying the cost of having a bit more delay on event execution).

Tunning this setting has a direct impact on potential Ethereum node API as a service cost, since bigger values have a direct impact in total API calls per day. Operators can also use this configuration to adjust to their budget.

type TxnEvents

type TxnEvents struct {
	TxnHash common.Hash
	Events  []interface{}
}

TxnEvents contains all events in a transaction.