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 SimpleStack
  • func NewSimpleStack(retentionLimit int) *SimpleStack
  • func (s *SimpleStack) Clear() error
  • func (s *SimpleStack) Peek() (*miniheader.MiniHeader, error)
  • func (s *SimpleStack) PeekAll() ([]*miniheader.MiniHeader, error)
  • func (s *SimpleStack) Pop() (*miniheader.MiniHeader, error)
  • func (s *SimpleStack) Push(miniHeader *miniheader.MiniHeader) error
• type Stack
• type Watcher
  • func New(config Config) *Watcher
  • func (w *Watcher) GetAllRetainedBlocks() ([]*miniheader.MiniHeader, error)
  • func (w *Watcher) GetLatestBlockProcessed() (*miniheader.MiniHeader, error)
  • func (w *Watcher) Subscribe(sink chan<- []*Event) event.Subscription
  • func (w *Watcher) SyncToLatestBlock(ctx context.Context) (blocksElapsed int, err 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
	StartBlockDepth rpc.BlockNumber
	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 SimpleStack

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

SimpleStack is a simple in-memory stack used in tests

func NewSimpleStack

func NewSimpleStack(retentionLimit int) *SimpleStack

NewSimpleStack instantiates a new SimpleStack

func (*SimpleStack) Clear

func (s *SimpleStack) Clear() error

Clear removes all items from the stack

func (*SimpleStack) Peek

func (s *SimpleStack) Peek() (*miniheader.MiniHeader, error)

Peek returns the top of the stack

func (*SimpleStack) PeekAll

func (s *SimpleStack) PeekAll() ([]*miniheader.MiniHeader, error)

PeekAll returns all the miniHeaders currently in the stack

func (*SimpleStack) Pop

func (s *SimpleStack) Pop() (*miniheader.MiniHeader, error)

Pop returns the top of the stack and removes it from the stack

func (*SimpleStack) Push

func (s *SimpleStack) Push(miniHeader *miniheader.MiniHeader) error

Push adds a miniheader.MiniHeader to the stack

type Stack

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

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

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) GetAllRetainedBlocks

func (w *Watcher) GetAllRetainedBlocks() ([]*miniheader.MiniHeader, error)

GetAllRetainedBlocks returns the blocks retained in-memory by the Watcher.

func (*Watcher) GetLatestBlockProcessed

func (w *Watcher) GetLatestBlockProcessed() (*miniheader.MiniHeader, error)

GetLatestBlockProcessed returns the latest block processed

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(ctx context.Context) (blocksElapsed int, err error)

SyncToLatestBlock 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) 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.