diff --git a/ethclient/ethclient.go b/ethclient/ethclient.go index f10626c01f..c761d4f8d3 100644 --- a/ethclient/ethclient.go +++ b/ethclient/ethclient.go @@ -85,11 +85,23 @@ func (ec *Client) BlockByHash(ctx context.Context, hash common.Hash) (*types.Blo return ec.getBlock(ctx, "eth_getBlockByHash", hash, true) } -// BlockByNumber returns a block from the current canonical chain. If number is nil, the -// latest known block is returned. +// BlockByNumber returns a block from the current canonical chain. +// If `number` is nil, the latest known block is returned. // -// Note that loading full blocks requires two requests. Use HeaderByNumber -// if you don't need all transactions or uncle headers. +// Use `HeaderByNumber` if you don't need full transaction data or uncle headers. +// +// Supported special block number tags: +// - `earliest` : The genesis (earliest) block +// - `latest` : The most recently included block +// - `safe` : The latest safe head block +// - `finalized` : The latest finalized block +// - `pending` : The pending block +// +// Example usage: +// +// ```go +// BlockByNumber(context.Background(), big.NewInt(int64(rpc.LatestBlockNumber))) +// ``` func (ec *Client) BlockByNumber(ctx context.Context, number *big.Int) (*types.Block, error) { return ec.getBlock(ctx, "eth_getBlockByNumber", toBlockNumArg(number), true) } @@ -210,8 +222,21 @@ func (ec *Client) HeaderByHash(ctx context.Context, hash common.Hash) (*types.He return head, err } -// HeaderByNumber returns a block header from the current canonical chain. If number is -// nil, the latest known header is returned. +// HeaderByNumber returns a block header from the current canonical chain. +// If `number` is nil, the latest known block header is returned. +// +// Supported special block number tags: +// - `earliest` : The genesis (earliest) block +// - `latest` : The most recently included block +// - `safe` : The latest safe head block +// - `finalized` : The latest finalized block +// - `pending` : The pending block +// +// Example usage: +// +// ```go +// HeaderByNumber(context.Background(), big.NewInt(int64(rpc.LatestBlockNumber))) +// ``` func (ec *Client) HeaderByNumber(ctx context.Context, number *big.Int) (*types.Header, error) { var head *types.Header err := ec.c.CallContext(ctx, &head, "eth_getBlockByNumber", toBlockNumArg(number), false)