blockwatch

Documentation

Index

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

Types

type Client

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

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

type Config

type Config struct {
	DB              *db.DB
	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 *types.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 FilterUnknownBlockError

type FilterUnknownBlockError struct {
	Message     string
	FilterQuery ethereum.FilterQuery
}

FilterUnknownBlockError is the error returned from a filter logs RPC call when the blockHash specified is not recognized.

func (FilterUnknownBlockError) Error

func (e FilterUnknownBlockError) Error() string

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(ctx context.Context, ethRPCClient ethrpcclient.Client) *RpcClient

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

func (*RpcClient) FilterLogs

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

FilterLogs returns the logs that satisfy the supplied filter query.

func (*RpcClient) HeaderByHash

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

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

func (*RpcClient) HeaderByNumber

func (rc *RpcClient) HeaderByNumber(number *big.Int) (*types.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 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 UnknownBlockHashError

type UnknownBlockHashError struct {
	BlockHash common.Hash
}

UnknownBlockHashError is the error returned from a filter logs RPC call when the blockHash specified is not recognized.

func (UnknownBlockHashError) Error

func (e UnknownBlockHashError) Error() string

type UnknownBlockNumberError

type UnknownBlockNumberError struct {
	Message     string
	BlockNumber *big.Int
}

UnknownBlockNumberError is the error returned from a filter logs RPC call when the block number specified is not recognized.

func (UnknownBlockNumberError) Error

func (e UnknownBlockNumberError) 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(ctx context.Context, retentionLimit int, config Config) (*Watcher, error)

New creates a new Watcher instance.

func (*Watcher) FastSyncToLatestBlock

func (w *Watcher) FastSyncToLatestBlock() (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) GetNumberOfBlocksBehind

func (w *Watcher) GetNumberOfBlocksBehind(ctx context.Context) (int, int, error)

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