blockwatch

Documentation

Index

• type Client
• type Config
• type Event
• type EventType
• type GetBlockByNumberResponse
• type RpcClient
  • func NewRpcClient(ethRPCClient ethrpcclient.Client) (*RpcClient, error)
  • func (rc *RpcClient) FilterLogs(q ethereum.FilterQuery) ([]types.Log, error)
  • func (rc *RpcClient) HeaderByHash(hash common.Hash) (*miniheader.MiniHeader, error)
  • func (rc *RpcClient) HeaderByNumber(number *big.Int) (*miniheader.MiniHeader, error)
• type Stack
• type TooMayBlocksBehindError
  • func (e TooMayBlocksBehindError) Error() string
• type Watcher
  • func New(config Config) *Watcher
  • func (w *Watcher) FastSyncToLatestBlock(ctx context.Context) (blocksElapsed int, err error)
  • func (w *Watcher) Subscribe(sink chan<- []*Event) event.Subscription
  • func (w *Watcher) SyncToLatestBlock() error
  • func (w *Watcher) Watch(ctx context.Context) error

Types

type Client

type Client interface {
	HeaderByNumber(number *big.Int) (*miniheader.MiniHeader, error)
	HeaderByHash(hash common.Hash) (*miniheader.MiniHeader, error)
	FilterLogs(q ethereum.FilterQuery) ([]types.Log, error)
}

Client defines the methods needed to satisfy the client expected when instantiating a Watcher instance.

type Config

type Config struct {
	Stack           Stack
	PollingInterval time.Duration
	WithLogs        bool
	Topics          []common.Hash
	Client          Client
}

Config holds some configuration options for an instance of BlockWatcher.

type Event

type Event struct {
	Type        EventType
	BlockHeader *miniheader.MiniHeader
}

Event describes a block event emitted by a Watcher

type EventType

type EventType int

EventType describes the types of events emitted by blockwatch.Watcher. A block can be discovered and added to our representation of the chain. During a block re-org, a block previously stored can be removed from the list.

const (
	Added EventType = iota
	Removed
)

type GetBlockByNumberResponse

type GetBlockByNumberResponse struct {
	Hash       common.Hash `json:"hash"`
	ParentHash common.Hash `json:"parentHash"`
	Number     string      `json:"number"`
	Timestamp  string      `json:"timestamp"`
}

type RpcClient

type RpcClient struct {
	// contains filtered or unexported fields
}

RpcClient is a Client for fetching Ethereum blocks from a specific JSON-RPC endpoint.

func NewRpcClient

func NewRpcClient(ethRPCClient ethrpcclient.Client) (*RpcClient, error)

NewRpcClient returns a new Client for fetching Ethereum blocks using the given ethclient.Client.

func (*RpcClient) FilterLogs

func (rc *RpcClient) FilterLogs(q ethereum.FilterQuery) ([]types.Log, error)

FilterLogs returns the logs that satisfy the supplied filter query.

func (*RpcClient) HeaderByHash

func (rc *RpcClient) HeaderByHash(hash common.Hash) (*miniheader.MiniHeader, error)

HeaderByHash fetches a block header by its block hash. If no block exists with this number it will return a `ethereum.NotFound` error.

func (*RpcClient) HeaderByNumber

func (rc *RpcClient) HeaderByNumber(number *big.Int) (*miniheader.MiniHeader, error)

HeaderByNumber fetches a block header by its number. If no `number` is supplied, it will return the latest block header. If no block exists with this number it will return a `ethereum.NotFound` error.

type Stack

type Stack interface {
	Pop() (*miniheader.MiniHeader, error)
	Push(*miniheader.MiniHeader) error
	Peek() (*miniheader.MiniHeader, error)
	PeekAll() ([]*miniheader.MiniHeader, error)
	Clear() error
	Checkpoint() (int, error)
	Reset(int) error
}

Stack defines the interface a stack must implement in order to be used by OrderWatcher for block header storage

type TooMayBlocksBehindError

type TooMayBlocksBehindError struct {
	// contains filtered or unexported fields
}

TooMayBlocksBehindError is an error returned if the BlockWatcher has fallen too many blocks behind the latest block (>128 blocks), and cannot catch back up when connect to a non-archive Ethereum node.

func (TooMayBlocksBehindError) Error

func (e TooMayBlocksBehindError) Error() string

type Watcher

type Watcher struct {
	// contains filtered or unexported fields
}

Watcher maintains a consistent representation of the latest X blocks (where X is enforced by the supplied stack) handling block re-orgs and network disruptions gracefully. It can be started from any arbitrary block height, and will emit both block added and removed events.

func New

func New(config Config) *Watcher

New creates a new Watcher instance.

func (*Watcher) FastSyncToLatestBlock

func (w *Watcher) FastSyncToLatestBlock(ctx context.Context) (blocksElapsed int, err error)

FastSyncToLatestBlock checks if the BlockWatcher is behind the latest block, and if so, catches it back up. If less than 128 blocks passed, we are able to fetch all missing block events and process them. If more than 128 blocks passed, we cannot catch up without an archive Ethereum node (see: http://bit.ly/2D11Hr6) so we instead clear previously tracked blocks so BlockWatcher starts again from the latest block. This function blocks until complete or the context is cancelled.

func (*Watcher) Subscribe

func (w *Watcher) Subscribe(sink chan<- []*Event) event.Subscription

Subscribe allows one to subscribe to the block events emitted by the Watcher. To unsubscribe, simply call `Unsubscribe` on the returned subscription. The sink channel should have ample buffer space to avoid blocking other subscribers. Slow subscribers are not dropped.

func (*Watcher) SyncToLatestBlock

func (w *Watcher) SyncToLatestBlock() error

SyncToLatestBlock syncs our local state of the chain to the latest block found via Ethereum RPC

func (*Watcher) Watch

func (w *Watcher) Watch(ctx context.Context) error

Watch starts the Watcher. It will continuously look for new blocks and blocks until there is a critical error or the given context is canceled. Typically, you want to call Watch inside a goroutine. For non-critical errors, callers must receive them from the Errors channel.