powchain

Documentation

Overview

Package powchain defines a runtime service which is tasked with communicating with an eth1 endpoint, processing logs from a deposit contract, and the latest eth1 data headers for usage in the beacon node.

Index

• Variables
• type Chain
• type ChainInfoFetcher
• type ChainStartFetcher
• type Client
• type POWBlockFetcher
• type RPCBlockFetcher
• type RPCClient
• type Reader
• type Service
  • func NewService(ctx context.Context, config *Web3ServiceConfig) (*Service, error)
  • func (s *Service) AreAllDepositsProcessed() (bool, error)
  • func (s *Service) BlockExists(ctx context.Context, hash common.Hash) (bool, *big.Int, error)
  • func (s *Service) BlockHashByHeight(ctx context.Context, height *big.Int) (common.Hash, error)
  • func (s *Service) BlockNumberByTimestamp(ctx context.Context, time uint64) (*big.Int, error)
  • func (s *Service) BlockTimeByHeight(ctx context.Context, height *big.Int) (uint64, error)
  • func (s *Service) ChainStartDeposits() []*ethpb.Deposit
  • func (s *Service) ChainStartEth1Data() *ethpb.Eth1Data
  • func (s *Service) ClearPreGenesisData()
  • func (s *Service) Client() Client
  • func (s *Service) DepositRoot() [32]byte
  • func (s *Service) DepositTrie() *trieutil.SparseMerkleTrie
  • func (s *Service) Eth2GenesisPowchainInfo() (uint64, *big.Int)
  • func (s *Service) IsConnectedToETH1() bool
  • func (s *Service) LatestBlockHash() common.Hash
  • func (s *Service) LatestBlockHeight() *big.Int
  • func (s *Service) PreGenesisState() *stateTrie.BeaconState
  • func (s *Service) ProcessChainStart(genesisTime uint64, eth1BlockHash [32]byte, blockNumber *big.Int)
  • func (s *Service) ProcessDepositLog(ctx context.Context, depositLog gethTypes.Log) error
  • func (s *Service) ProcessETH1Block(ctx context.Context, blkNum *big.Int) error
  • func (s *Service) ProcessLog(ctx context.Context, depositLog gethTypes.Log) error
  • func (s *Service) Start()
  • func (s *Service) Status() error
  • func (s *Service) Stop() error
• type Web3ServiceConfig

Variables

var (
	// ErrNotABlockInfo will be returned when a cache object is not a pointer to
	// a blockInfo struct.
	ErrNotABlockInfo = errors.New("object is not a block info")
)

Types

type Chain

type Chain interface {
	ChainStartFetcher
	ChainInfoFetcher
	POWBlockFetcher
}

Chain defines a standard interface for the powchain service in Prysm.

type ChainInfoFetcher

type ChainInfoFetcher interface {
	Eth2GenesisPowchainInfo() (uint64, *big.Int)
	IsConnectedToETH1() bool
}

ChainInfoFetcher retrieves information about eth1 metadata at the eth2 genesis time.

type ChainStartFetcher

type ChainStartFetcher interface {
	ChainStartDeposits() []*ethpb.Deposit
	ChainStartEth1Data() *ethpb.Eth1Data
	PreGenesisState() *stateTrie.BeaconState
	ClearPreGenesisData()
}

ChainStartFetcher retrieves information pertaining to the chain start event of the beacon chain for usage across various services.

type Client

type Client interface {
	Reader
	RPCBlockFetcher
	bind.ContractFilterer
	bind.ContractCaller
}

Client defines a struct that combines all relevant ETH1.0 mainchain interactions required by the beacon chain node.

type POWBlockFetcher

type POWBlockFetcher interface {
	BlockTimeByHeight(ctx context.Context, height *big.Int) (uint64, error)
	BlockNumberByTimestamp(ctx context.Context, time uint64) (*big.Int, error)
	BlockHashByHeight(ctx context.Context, height *big.Int) (common.Hash, error)
	BlockExists(ctx context.Context, hash common.Hash) (bool, *big.Int, error)
}

POWBlockFetcher defines a struct that can retrieve mainchain blocks.

type RPCBlockFetcher

type RPCBlockFetcher interface {
	HeaderByNumber(ctx context.Context, number *big.Int) (*gethTypes.Header, error)
	BlockByNumber(ctx context.Context, number *big.Int) (*gethTypes.Block, error)
	BlockByHash(ctx context.Context, hash common.Hash) (*gethTypes.Block, error)
}

RPCBlockFetcher defines a subset of methods conformed to by ETH1.0 RPC clients for fetching block information.

type RPCClient

type RPCClient interface {
	BatchCall(b []gethRPC.BatchElem) error
}

RPCClient defines the rpc methods required to interact with the eth1 node.

type Reader

type Reader interface {
	SubscribeNewHead(ctx context.Context, ch chan<- *gethTypes.Header) (ethereum.Subscription, error)
}

Reader defines a struct that can fetch latest header events from a web3 endpoint.

type Service

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

Service fetches important information about the canonical Ethereum ETH1.0 chain via a web3 endpoint using an ethclient. The Random Beacon Chain requires synchronization with the ETH1.0 chain's current blockhash, block number, and access to logs within the Validator Registration Contract on the ETH1.0 chain to kick off the beacon chain's validator registration process.

func NewService

func NewService(ctx context.Context, config *Web3ServiceConfig) (*Service, error)

NewService sets up a new instance with an ethclient when given a web3 endpoint as a string in the config.

func (*Service) AreAllDepositsProcessed

func (s *Service) AreAllDepositsProcessed() (bool, error)

AreAllDepositsProcessed determines if all the logs from the deposit contract are processed.

func (*Service) BlockExists

func (s *Service) BlockExists(ctx context.Context, hash common.Hash) (bool, *big.Int, error)

BlockExists returns true if the block exists, it's height and any possible error encountered.

func (*Service) BlockHashByHeight

func (s *Service) BlockHashByHeight(ctx context.Context, height *big.Int) (common.Hash, error)

BlockHashByHeight returns the block hash of the block at the given height.

func (*Service) BlockNumberByTimestamp

func (s *Service) BlockNumberByTimestamp(ctx context.Context, time uint64) (*big.Int, error)

BlockNumberByTimestamp returns the most recent block number up to a given timestamp. This is a naive implementation that will use O(ETH1_FOLLOW_DISTANCE) calls to cache or ETH1. This is called for multiple times but only changes every SlotsPerEth1VotingPeriod (1024 slots) so the whole method should be cached.

func (*Service) BlockTimeByHeight

func (s *Service) BlockTimeByHeight(ctx context.Context, height *big.Int) (uint64, error)

BlockTimeByHeight fetches an eth1.0 block timestamp by its height.

func (*Service) ChainStartDeposits

func (s *Service) ChainStartDeposits() []*ethpb.Deposit

ChainStartDeposits returns a slice of validator deposit data processed by the deposit contract and cached in the powchain service.

func (*Service) ChainStartEth1Data

func (s *Service) ChainStartEth1Data() *ethpb.Eth1Data

ChainStartEth1Data returns the eth1 data at chainstart.

func (*Service) ClearPreGenesisData

func (s *Service) ClearPreGenesisData()

ClearPreGenesisData clears out the stored chainstart deposits and beacon state.

func (*Service) Client

func (s *Service) Client() Client

Client for interacting with the ETH1.0 chain.

func (*Service) DepositRoot

func (s *Service) DepositRoot() [32]byte

DepositRoot returns the Merkle root of the latest deposit trie from the ETH1.0 deposit contract.

func (*Service) DepositTrie

func (s *Service) DepositTrie() *trieutil.SparseMerkleTrie

DepositTrie returns the sparse Merkle trie used for storing deposits from the ETH1.0 deposit contract.

func (*Service) Eth2GenesisPowchainInfo

func (s *Service) Eth2GenesisPowchainInfo() (uint64, *big.Int)

Eth2GenesisPowchainInfo retrieves the genesis time and eth1 block number of the beacon chain from the deposit contract.

func (*Service) IsConnectedToETH1

func (s *Service) IsConnectedToETH1() bool

IsConnectedToETH1 checks if the beacon node is connected to a ETH1 Node.

func (*Service) LatestBlockHash

func (s *Service) LatestBlockHash() common.Hash

LatestBlockHash in the ETH1.0 chain.

func (*Service) LatestBlockHeight

func (s *Service) LatestBlockHeight() *big.Int

LatestBlockHeight in the ETH1.0 chain.

func (*Service) PreGenesisState

func (s *Service) PreGenesisState() *stateTrie.BeaconState

PreGenesisState returns a state that contains pre-chainstart deposits.

func (*Service) ProcessChainStart

func (s *Service) ProcessChainStart(genesisTime uint64, eth1BlockHash [32]byte, blockNumber *big.Int)

ProcessChainStart processes the log which had been received from the ETH1.0 chain by trying to determine when to start the beacon chain.

func (*Service) ProcessDepositLog

func (s *Service) ProcessDepositLog(ctx context.Context, depositLog gethTypes.Log) error

ProcessDepositLog processes the log which had been received from the ETH1.0 chain by trying to ascertain which participant deposited in the contract.

func (*Service) ProcessETH1Block

func (s *Service) ProcessETH1Block(ctx context.Context, blkNum *big.Int) error

ProcessETH1Block processes the logs from the provided eth1Block.

func (*Service) ProcessLog

func (s *Service) ProcessLog(ctx context.Context, depositLog gethTypes.Log) error

ProcessLog is the main method which handles the processing of all logs from the deposit contract on the ETH1.0 chain.

func (*Service) Start

func (s *Service) Start()

Start a web3 service's main event loop.

func (*Service) Status

func (s *Service) Status() error

Status is service health checks. Return nil or error.

func (*Service) Stop

func (s *Service) Stop() error

Stop the web3 service's main event loop and associated goroutines.

type Web3ServiceConfig

type Web3ServiceConfig struct {
	ETH1Endpoint    string
	HTTPEndPoint    string
	DepositContract common.Address
	BeaconDB        db.HeadAccessDatabase
	DepositCache    *depositcache.DepositCache
	StateNotifier   statefeed.Notifier
}

Web3ServiceConfig defines a config struct for web3 service to use through its life cycle.