sources

package
v0.10.10 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 13, 2023 License: MIT Imports: 22 Imported by: 8

Documentation

Index

Constants

This section is empty.

Variables

Functions

func LimitRPC

func LimitRPC(c client.RPC, concurrentRequests int) client.RPC

LimitRPC limits concurrent RPC requests (excluding subscriptions) to a given number by wrapping the client with a semaphore.

func NewReceiptsFetchingJob added in v0.10.5

func NewReceiptsFetchingJob(requester ReceiptsRequester, client rpcClient, maxBatchSize int, block eth.BlockID,
	receiptHash common.Hash, txHashes []common.Hash) *receiptsFetchingJob

func ValidRPCProviderKind added in v0.10.5

func ValidRPCProviderKind(value RPCProviderKind) bool

Types

type BatchCallContextFn

type BatchCallContextFn func(ctx context.Context, b []rpc.BatchElem) error

type CallContextFn added in v0.10.5

type CallContextFn func(ctx context.Context, result any, method string, args ...any) error

type EngineClient

type EngineClient struct {
	*L2Client
}

EngineClient extends L2Client with engine API bindings.

func NewEngineClient

func NewEngineClient(client client.RPC, log log.Logger, metrics caching.Metrics, config *EngineClientConfig) (*EngineClient, error)

func (*EngineClient) ForkchoiceUpdate

func (s *EngineClient) ForkchoiceUpdate(ctx context.Context, fc *eth.ForkchoiceState, attributes *eth.PayloadAttributes) (*eth.ForkchoiceUpdatedResult, error)

ForkchoiceUpdate updates the forkchoice on the execution client. If attributes is not nil, the engine client will also begin building a block based on attributes after the new head block and return the payload ID.

The RPC may return three types of errors: 1. Processing error: ForkchoiceUpdatedResult.PayloadStatusV1.ValidationError or other non-success PayloadStatusV1, 2. `error` as eth.InputError: the forkchoice state or attributes are not valid. 3. Other types of `error`: temporary RPC errors, like timeouts.

func (*EngineClient) GetPayload

func (s *EngineClient) GetPayload(ctx context.Context, payloadId eth.PayloadID) (*eth.ExecutionPayload, error)

GetPayload gets the execution payload associated with the PayloadId. There may be two types of error: 1. `error` as eth.InputError: the payload ID may be unknown 2. Other types of `error`: temporary RPC errors, like timeouts.

func (*EngineClient) NewPayload

func (s *EngineClient) NewPayload(ctx context.Context, payload *eth.ExecutionPayload) (*eth.PayloadStatusV1, error)

NewPayload executes a full block on the execution engine. This returns a PayloadStatusV1 which encodes any validation/processing error, and this type of error is kept separate from the returned `error` used for RPC errors, like timeouts.

type EngineClientConfig

type EngineClientConfig struct {
	L2ClientConfig
}

func EngineClientDefaultConfig

func EngineClientDefaultConfig(config *rollup.Config) *EngineClientConfig

type EthClient

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

EthClient retrieves ethereum data with optimized batch requests, cached results, and flag to not trust the RPC.

func NewEthClient

func NewEthClient(client client.RPC, log log.Logger, metrics caching.Metrics, config *EthClientConfig) (*EthClient, error)

NewEthClient wraps a RPC with bindings to fetch ethereum data, while logging errors, parallel-requests constraint, tracking metrics (optional), and caching.

func (*EthClient) Close

func (s *EthClient) Close()

func (*EthClient) FetchReceipts

func (s *EthClient) FetchReceipts(ctx context.Context, blockHash common.Hash) (eth.BlockInfo, types.Receipts, error)

FetchReceipts returns a block info and all of the receipts associated with transactions in the block. It verifies the receipt hash in the block header against the receipt hash of the fetched receipts to ensure that the execution engine did not fail to return any receipts.

func (*EthClient) GetProof

func (s *EthClient) GetProof(ctx context.Context, address common.Address, storage []common.Hash, blockTag string) (*eth.AccountResult, error)

GetProof returns an account proof result, with any optional requested storage proofs. The retrieval does sanity-check that storage proofs for the expected keys are present in the response, but does not verify the result. Call accountResult.Verify(stateRoot) to verify the result.

func (*EthClient) GetStorageAt added in v0.10.5

func (s *EthClient) GetStorageAt(ctx context.Context, address common.Address, storageSlot common.Hash, blockTag string) (common.Hash, error)

GetStorageAt returns the storage value at the given address and storage slot, **without verifying the correctness of the result**. This should only ever be used as alternative to GetProof when the user opts in. E.g. Erigon L1 node users may have to use this, since Erigon does not support eth_getProof, see https://github.com/ledgerwatch/erigon/issues/1349

func (*EthClient) InfoAndTxsByHash

func (s *EthClient) InfoAndTxsByHash(ctx context.Context, hash common.Hash) (eth.BlockInfo, types.Transactions, error)

func (*EthClient) InfoAndTxsByLabel

func (s *EthClient) InfoAndTxsByLabel(ctx context.Context, label eth.BlockLabel) (eth.BlockInfo, types.Transactions, error)

func (*EthClient) InfoAndTxsByNumber

func (s *EthClient) InfoAndTxsByNumber(ctx context.Context, number uint64) (eth.BlockInfo, types.Transactions, error)

func (*EthClient) InfoByHash

func (s *EthClient) InfoByHash(ctx context.Context, hash common.Hash) (eth.BlockInfo, error)

func (*EthClient) InfoByLabel

func (s *EthClient) InfoByLabel(ctx context.Context, label eth.BlockLabel) (eth.BlockInfo, error)

func (*EthClient) InfoByNumber

func (s *EthClient) InfoByNumber(ctx context.Context, number uint64) (eth.BlockInfo, error)

func (*EthClient) OnReceiptsMethodErr added in v0.10.5

func (s *EthClient) OnReceiptsMethodErr(m ReceiptsFetchingMethod, err error)

func (*EthClient) PayloadByHash

func (s *EthClient) PayloadByHash(ctx context.Context, hash common.Hash) (*eth.ExecutionPayload, error)

func (*EthClient) PayloadByLabel

func (s *EthClient) PayloadByLabel(ctx context.Context, label eth.BlockLabel) (*eth.ExecutionPayload, error)

func (*EthClient) PayloadByNumber

func (s *EthClient) PayloadByNumber(ctx context.Context, number uint64) (*eth.ExecutionPayload, error)

func (*EthClient) PickReceiptsMethod added in v0.10.5

func (s *EthClient) PickReceiptsMethod(txCount uint64) ReceiptsFetchingMethod

func (*EthClient) ReadStorageAt added in v0.10.5

func (s *EthClient) ReadStorageAt(ctx context.Context, address common.Address, storageSlot common.Hash, blockHash common.Hash) (common.Hash, error)

ReadStorageAt is a convenience method to read a single storage value at the given slot in the given account. The storage slot value is verified against the state-root of the given block if we do not trust the RPC provider, or directly retrieved without proof if we do trust the RPC.

func (*EthClient) SubscribeNewHead

func (s *EthClient) SubscribeNewHead(ctx context.Context, ch chan<- *types.Header) (ethereum.Subscription, error)

SubscribeNewHead subscribes to notifications about the current blockchain head on the given channel.

type EthClientConfig

type EthClientConfig struct {
	// Maximum number of requests to make per batch
	MaxRequestsPerBatch int

	// limit concurrent requests, applies to the source as a whole
	MaxConcurrentRequests int

	// Number of blocks worth of receipts to cache
	ReceiptsCacheSize int
	// Number of blocks worth of transactions to cache
	TransactionsCacheSize int
	// Number of block headers to cache
	HeadersCacheSize int
	// Number of payloads to cache
	PayloadsCacheSize int

	// If the RPC is untrusted, then we should not use cached information from responses,
	// and instead verify against the block-hash.
	// Of real L1 blocks no deposits can be missed/faked, no batches can be missed/faked,
	// only the wrong L1 blocks can be retrieved.
	TrustRPC bool

	// If the RPC must ensure that the results fit the ExecutionPayload(Header) format.
	// If this is not checked, disabled header fields like the nonce or difficulty
	// may be used to get a different block-hash.
	MustBePostMerge bool

	// RPCProviderKind is a hint at what type of RPC provider we are dealing with
	RPCProviderKind RPCProviderKind
}

func (*EthClientConfig) Check

func (c *EthClientConfig) Check() error

type HeaderInfo

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

HeaderInfo contains all the header-info required to implement the eth.BlockInfo interface, used in the rollup state-transition, with pre-computed block hash.

func (*HeaderInfo) BaseFee

func (info *HeaderInfo) BaseFee() *big.Int

func (*HeaderInfo) Coinbase

func (info *HeaderInfo) Coinbase() common.Address

func (*HeaderInfo) Hash

func (info *HeaderInfo) Hash() common.Hash

func (*HeaderInfo) ID

func (info *HeaderInfo) ID() eth.BlockID

func (*HeaderInfo) MixDigest

func (info *HeaderInfo) MixDigest() common.Hash

func (*HeaderInfo) NumberU64

func (info *HeaderInfo) NumberU64() uint64

func (*HeaderInfo) ParentHash

func (info *HeaderInfo) ParentHash() common.Hash

func (*HeaderInfo) ReceiptHash

func (info *HeaderInfo) ReceiptHash() common.Hash

func (*HeaderInfo) Root

func (info *HeaderInfo) Root() common.Hash

func (*HeaderInfo) Time

func (info *HeaderInfo) Time() uint64

type IterativeBatchCall

type IterativeBatchCall[K any, V any] struct {
	// contains filtered or unexported fields
}

IterativeBatchCall is an util to create a job to fetch many RPC requests in batches, and enable the caller to parallelize easily and safely, handle and re-try errors, and pick a batch size all by simply calling Fetch again and again until it returns io.EOF.

func NewIterativeBatchCall

func NewIterativeBatchCall[K any, V any](
	requestsKeys []K,
	makeRequest func(K) (V, rpc.BatchElem),
	getBatch BatchCallContextFn,
	batchSize int) *IterativeBatchCall[K, V]

NewIterativeBatchCall constructs a batch call, fetching the values with the given keys, and transforms them into a verified final result.

func (*IterativeBatchCall[K, V]) Complete

func (ibc *IterativeBatchCall[K, V]) Complete() bool

Complete indicates if the batch call is done.

func (*IterativeBatchCall[K, V]) Fetch

func (ibc *IterativeBatchCall[K, V]) Fetch(ctx context.Context) error

Fetch fetches more of the data, and returns io.EOF when all data has been fetched. This method is safe to call concurrently: it will parallelize the fetching work. If no work is available, but the fetching is not done yet, then Fetch will block until the next thing can be fetched, or until the context expires.

func (*IterativeBatchCall[K, V]) Reset

func (ibc *IterativeBatchCall[K, V]) Reset()

Reset will clear the batch call, to start fetching all contents from scratch.

func (*IterativeBatchCall[K, V]) Result

func (ibc *IterativeBatchCall[K, V]) Result() ([]V, error)

Result returns the fetched values, checked and transformed to the final output type, if available. If the check fails, the IterativeBatchCall will Reset itself, to be ready for a re-attempt in fetching new data.

type L1Client

type L1Client struct {
	*EthClient
	// contains filtered or unexported fields
}

L1Client provides typed bindings to retrieve L1 data from an RPC source, with optimized batch requests, cached results, and flag to not trust the RPC (i.e. to verify all returned contents against corresponding block hashes).

func NewL1Client

func NewL1Client(client client.RPC, log log.Logger, metrics caching.Metrics, config *L1ClientConfig) (*L1Client, error)

NewL1Client wraps a RPC with bindings to fetch L1 data, while logging errors, tracking metrics (optional), and caching.

func (*L1Client) L1BlockRefByHash

func (s *L1Client) L1BlockRefByHash(ctx context.Context, hash common.Hash) (eth.L1BlockRef, error)

func (*L1Client) L1BlockRefByLabel

func (s *L1Client) L1BlockRefByLabel(ctx context.Context, label eth.BlockLabel) (eth.L1BlockRef, error)

func (*L1Client) L1BlockRefByNumber

func (s *L1Client) L1BlockRefByNumber(ctx context.Context, num uint64) (eth.L1BlockRef, error)

type L1ClientConfig

type L1ClientConfig struct {
	EthClientConfig

	L1BlockRefsCacheSize int
}

func L1ClientDefaultConfig

func L1ClientDefaultConfig(config *rollup.Config, trustRPC bool, kind RPCProviderKind) *L1ClientConfig

type L2Client

type L2Client struct {
	*EthClient
	// contains filtered or unexported fields
}

L2Client extends EthClient with functions to fetch and cache eth.L2BlockRef values.

func NewL2Client

func NewL2Client(client client.RPC, log log.Logger, metrics caching.Metrics, config *L2ClientConfig) (*L2Client, error)

func (*L2Client) L2BlockRefByHash

func (s *L2Client) L2BlockRefByHash(ctx context.Context, hash common.Hash) (eth.L2BlockRef, error)

L2BlockRefByHash returns the L2 block reference for the given block hash. The returned BlockRef may not be in the canonical chain.

func (*L2Client) L2BlockRefByLabel

func (s *L2Client) L2BlockRefByLabel(ctx context.Context, label eth.BlockLabel) (eth.L2BlockRef, error)

L2BlockRefByLabel returns the L2 block reference for the given label.

func (*L2Client) L2BlockRefByNumber

func (s *L2Client) L2BlockRefByNumber(ctx context.Context, num uint64) (eth.L2BlockRef, error)

L2BlockRefByNumber returns the L2 block reference for the given block number.

func (*L2Client) SystemConfigByL2Hash

func (s *L2Client) SystemConfigByL2Hash(ctx context.Context, hash common.Hash) (eth.SystemConfig, error)

SystemConfigByL2Hash returns the system config (matching the config updates up to and including the L1 origin) for the given L2 block hash. The returned SystemConfig may not be in the canonical chain when the hash is not canonical.

type L2ClientConfig

type L2ClientConfig struct {
	EthClientConfig

	L2BlockRefsCacheSize int
	L1ConfigsCacheSize   int

	RollupCfg *rollup.Config
}

func L2ClientDefaultConfig

func L2ClientDefaultConfig(config *rollup.Config, trustRPC bool) *L2ClientConfig

type RPCProviderKind added in v0.10.5

type RPCProviderKind string

RPCProviderKind identifies an RPC provider, used to hint at the optimal receipt fetching approach.

const (
	RPCKindAlchemy    RPCProviderKind = "alchemy"
	RPCKindQuickNode  RPCProviderKind = "quicknode"
	RPCKindInfura     RPCProviderKind = "infura"
	RPCKindParity     RPCProviderKind = "parity"
	RPCKindNethermind RPCProviderKind = "nethermind"
	RPCKindDebugGeth  RPCProviderKind = "debug_geth"
	RPCKindErigon     RPCProviderKind = "erigon"
	RPCKindBasic      RPCProviderKind = "basic" // try only the standard most basic receipt fetching
	RPCKindAny        RPCProviderKind = "any"   // try any method available
)

func (*RPCProviderKind) Set added in v0.10.5

func (kind *RPCProviderKind) Set(value string) error

func (RPCProviderKind) String added in v0.10.5

func (kind RPCProviderKind) String() string

type ReceiptsFetchingMethod added in v0.10.5

type ReceiptsFetchingMethod uint64

ReceiptsFetchingMethod is a bitfield with 1 bit for each receipts fetching type. Depending on errors, tx counts and preferences the code may select different sets of fetching methods.

const (
	// EthGetTransactionReceiptBatch is standard per-tx receipt fetching with JSON-RPC batches.
	// Available in: standard, everywhere.
	//   - Alchemy: 15 CU / tx
	//   - Quicknode: 2 credits / tx
	// Method: eth_getTransactionReceipt
	// See: https://ethereum.github.io/execution-apis/api-documentation/
	EthGetTransactionReceiptBatch ReceiptsFetchingMethod = 1 << iota
	// AlchemyGetTransactionReceipts is a special receipt fetching method provided by Alchemy.
	// Available in:
	//   - Alchemy: 250 CU total
	// Method: alchemy_getTransactionReceipts
	// Params:
	//   - object with "blockNumber" or "blockHash" field
	// Returns: "array of receipts" - docs lie, array is wrapped in a struct with single "receipts" field
	// See: https://docs.alchemy.com/reference/alchemy-gettransactionreceipts#alchemy_gettransactionreceipts
	AlchemyGetTransactionReceipts
	// DebugGetRawReceipts is a debug method from Geth, faster by avoiding serialization and metadata overhead.
	// Ideal for fast syncing from a local geth node.
	// Available in:
	//   - Geth: free
	//   - QuickNode: 22 credits maybe? Unknown price, undocumented ("debug_getblockreceipts" exists in table though?)
	// Method: debug_getRawReceipts
	// Params:
	//   - string presenting a block number or hash
	// Returns: list of strings, hex encoded RLP of receipts data. "consensus-encoding of all receipts in a single block"
	// See: https://geth.ethereum.org/docs/rpc/ns-debug#debug_getrawreceipts
	DebugGetRawReceipts
	// ParityGetBlockReceipts is an old parity method, which has been adopted by Nethermind and some RPC providers.
	// Available in:
	//   - Alchemy: 500 CU total
	//   - QuickNode: 59 credits - docs are wrong, not actually available anymore.
	//   - Any open-ethereum/parity legacy: free
	//   - Nethermind: free
	// Method: parity_getBlockReceipts
	// Params:
	//   Parity: "quantity or tag"
	//   Alchemy: string with block hash, number in hex, or block tag.
	//   Nethermind: very flexible: tag, number, hex or object with "requireCanonical"/"blockHash" fields.
	// Returns: array of receipts
	// See:
	//   - Parity: https://openethereum.github.io/JSONRPC-parity-module#parity_getblockreceipts
	//   - QuickNode: undocumented.
	//   - Alchemy: https://docs.alchemy.com/reference/eth-getblockreceipts
	//   - Nethermind: https://docs.nethermind.io/nethermind/ethereum-client/json-rpc/parity#parity_getblockreceipts
	ParityGetBlockReceipts
	// EthGetBlockReceipts is a non-standard receipt fetching method in the eth namespace,
	// supported by some RPC platforms and Erigon.
	// Available in:
	//   - Alchemy: 500 CU total  (and deprecated)
	//   - Erigon: free
	//   - QuickNode: 59 credits total       (does not seem to work with block hash arg, inaccurate docs)
	// Method: eth_getBlockReceipts
	// Params:
	//   - QuickNode: string, "quantity or tag", docs say incl. block hash, but API does not actually accept it.
	//   - Alchemy: string, block hash / num (hex) / block tag
	// Returns: array of receipts
	// See:
	//   - QuickNode: https://www.quicknode.com/docs/ethereum/eth_getBlockReceipts
	//   - Alchemy: https://docs.alchemy.com/reference/eth-getblockreceipts
	EthGetBlockReceipts
)

func AvailableReceiptsFetchingMethods added in v0.10.5

func AvailableReceiptsFetchingMethods(kind RPCProviderKind) ReceiptsFetchingMethod

AvailableReceiptsFetchingMethods selects receipt fetching methods based on the RPC provider kind.

func PickBestReceiptsFetchingMethod added in v0.10.5

func PickBestReceiptsFetchingMethod(kind RPCProviderKind, available ReceiptsFetchingMethod, txCount uint64) ReceiptsFetchingMethod

PickBestReceiptsFetchingMethod selects an RPC method that is still available, and optimal for fetching the given number of tx receipts from the specified provider kind.

func (ReceiptsFetchingMethod) String added in v0.10.5

func (r ReceiptsFetchingMethod) String() string

type ReceiptsRequester added in v0.10.5

type ReceiptsRequester interface {
	PickReceiptsMethod(txCount uint64) ReceiptsFetchingMethod
	OnReceiptsMethodErr(m ReceiptsFetchingMethod, err error)
}

ReceiptsRequester helps determine which receipts fetching method can be used, and is given feedback upon receipt fetching errors to adapt the choice of method.

type RollupClient

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

func NewRollupClient

func NewRollupClient(rpc client.RPC) *RollupClient

func (*RollupClient) OutputAtBlock

func (r *RollupClient) OutputAtBlock(ctx context.Context, blockNum uint64) (*eth.OutputResponse, error)

func (*RollupClient) RollupConfig

func (r *RollupClient) RollupConfig(ctx context.Context) (*rollup.Config, error)

func (*RollupClient) SyncStatus

func (r *RollupClient) SyncStatus(ctx context.Context) (*eth.SyncStatus, error)

func (*RollupClient) Version

func (r *RollupClient) Version(ctx context.Context) (string, error)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL