client

README

go-execution-client

Go library providing an abstraction to Ethereum execution nodes. Its external API follows the official Ethereum consensus APIs specification.

This library is under development; expect APIs and data structures to change until it reaches version 1.0. In addition, clients' implementations of both their own and the standard API are themselves under development so implementation of the the full API can be incomplete.

Table of Contents

• Install
• Usage
• Maintainers
• Contribute
• License

Install

go-execution-client is a standard Go module which can be installed with:

go get github.com/attestantio/go-execution-client

Support

go-execution-client supports execution nodes that comply with the standard execution node API.

Usage

Please read the Go documentation for this library for interface information.

Example

Below is a complete annotated example to access an execution node.

package main

import (
    "context"
    "fmt"

    execclient "github.com/attestantio/go-execution-client"
    "github.com/attestantio/go-execution-client/jsonrpc"
    "github.com/rs/zerolog"
)

func main() {
    // Provide a cancellable context to the creation function.
    ctx, cancel := context.WithCancel(context.Background())
    client, err := jsonrpc.New(ctx,
        // WithAddress supplies the address of the execution node, as a URL.
        jsonrpc.WithAddress("http://localhost:8545/"),
        // LogLevel supplies the level of logging to carry out.
        jsonrpc.WithLogLevel(zerolog.WarnLevel),
    )
    if err != nil {
        panic(err)
    }

    fmt.Printf("Connected to %s\n", client.Name())

    // Client functions have their own interfaces.  Not all functions are
    // supported by all clients, so checks should be made for each function when
    // casting the service to the relevant interface.
    if provider, isProvider := client.(execclient.ChainHeightProvider); isProvider {
        chainHeight, err := provider.ChainHeight(ctx)
        if err != nil {
            panic(err)
        }
        fmt.Printf("Chain height is %v\n", chainHeight)
    }

    // Cancelling the context passed to New() frees up resources held by the
    // client, closes connections, clears handlers, etc.
    cancel()
}

Maintainers

Jim McDonald: @mcdee.

Contribute

Contributions welcome. Please check out the issues.

License

Apache-2.0 © 2021 Attestant Limited

Documentation

Index

• type BalancesProvider
• type BlockReplaysProvider
• type BlocksProvider
• type ChainHeightProvider
• type ChainIDProvider
• type EventsProvider
• type IssuanceProvider
• type NetworkIDProvider
• type NewPendingTransactionsProvider
• type Service
• type SyncingProvider
• type TransactionReceiptsProvider
• type TransactionsProvider

Types

type BalancesProvider

type BalancesProvider interface {
	// Balance obtains the balance for the given address at the given block ID.
	Balance(ctx context.Context, address types.Address, blockID string) (*big.Int, error)
}

BalancesProvider is the interface for providing balances.

type BlockReplaysProvider

type BlockReplaysProvider interface {
	// ReplayBlockTransactions obtains traces for all transactions in a block.
	ReplayBlockTransactions(ctx context.Context, blockID string) ([]*api.TransactionResult, error)
}

BlockReplaysProvider is the interface for providing block replays.

type BlocksProvider

type BlocksProvider interface {
	// Block returns the block with the given ID.
	Block(ctx context.Context, blockID string) (*spec.Block, error)
}

BlocksProvider is the interface for providing blocks.

type ChainHeightProvider

type ChainHeightProvider interface {
	// ChainHeight returns the height of the chain as understood by the node.
	ChainHeight(ctx context.Context) (uint32, error)
}

ChainHeightProvider is the interface for providing chain height.

type ChainIDProvider

type ChainIDProvider interface {
	// ChainID returns the chain ID.
	ChainID(ctx context.Context) (uint64, error)
}

ChainIDProvider is the interface for providing the chain ID.

type EventsProvider

type EventsProvider interface {
	// Events returns the events matching the filter.
	Events(ctx context.Context, filter *api.EventsFilter) ([]*spec.BerlinTransactionEvent, error)
}

EventsProvider is the interface for providing events.

type IssuanceProvider

type IssuanceProvider interface {
	// Issuance returns the issuance of a block.
	Issuance(ctx context.Context, blockID string) (*api.Issuance, error)
}

IssuanceProvider is the interface for providing issuance.

type NetworkIDProvider

type NetworkIDProvider interface {
	// NetworkID returns the network ID.
	NetworkID(ctx context.Context) (uint64, error)
}

NetworkIDProvider is the interface for providing the network ID.

type NewPendingTransactionsProvider

type NewPendingTransactionsProvider interface {
	// NewPendingTransactions subscribes to new pending transactions.
	NewPendingTransactions(ctx context.Context, ch chan *spec.Transaction) (*util.Subscription, error)
}

NewPendingTransactionsProvider is the interface for providing new pending transactions.

type Service

type Service interface {
	// Name returns the name of the client implementation.
	Name() string

	// Address returns the address of the client.
	Address() string
}

Service is the service providing a connection to an execution client.

type SyncingProvider

type SyncingProvider interface {
	// Syncing obtains information about the sync state of the node.
	Syncing(ctx context.Context) (*api.SyncState, error)
}

SyncingProvider is the interface for providing syncing information.

type TransactionReceiptsProvider

type TransactionReceiptsProvider interface {
	// TransactionReceipt returns the transaction receipt for the given transaction hash.
	TransactionReceipt(ctx context.Context, hash types.Hash) (*spec.BerlinTransactionReceipt, error)
}

TransactionReceiptsProvider is the interface for providing transaction receipts.

type TransactionsProvider

type TransactionsProvider interface {
	// Transaction returns the transaction for the given transaction hash.
	Transaction(ctx context.Context, hash types.Hash) (*spec.Transaction, error)

	// TransactionInBlock returns the transaction for the given transaction in a block at the given index.
	TransactionInBlock(ctx context.Context, blockHash types.Hash, index uint32) (*spec.Transaction, error)
}

TransactionsProvider is the interface for providing transactions.