client

package module
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Oct 8, 2021 License: Apache-2.0 Imports: 6 Imported by: 209

README

go-eth2-client

Tag License GoDoc Lint Go Report Card

Go library providing an abstraction to multiple Ethereum 2 beacon nodes. Its external API follows the official Ethereum beacon 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

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

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

Support

go-eth2-client supports beacon nodes that comply with the standard beacon node API. To date it has been tested against the following beacon nodes:

Note that the gRPC interface for Prysm is still available in the grpc module, however it does not support Altair and is considered deprecated. The http module should be used instead. gRPC is no longer selected as part of the auto module, which is also deprecated in favour of instantiating the http module directly.

Usage

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

Example

Below is a complete annotated example to access a beacon node.

package main

import (
    "context"
    "fmt"
    
    eth2client "github.com/attestantio/go-eth2-client"
    "github.com/attestantio/go-eth2-client/http"
    "github.com/rs/zerolog"
)

func main() {
    // Provide a cancellable context to the creation function.
    ctx, cancel := context.WithCancel(context.Background())
    client, err := http.New(ctx,
        // WithAddress supplies the address of the beacon node, as a URL.
        http.WithAddress("http://localhost:5052/"),
        // LogLevel supplies the level of logging to carry out.
        http.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.(eth2client.GenesisProvider); isProvider {
        genesis, err := provider.Genesis(ctx)
        if err != nil {
            panic(err)
        }
        fmt.Printf("Genesis time is %v\n", genesis.GenesisTime)
    }

    // 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 © 2020, 2021 Attestant Limited

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AggregateAttestationProvider 

type AggregateAttestationProvider interface {
	// AggregateAttestation fetches the aggregate attestation given an attestation.
	AggregateAttestation(ctx context.Context, slot phase0.Slot, attestationDataRoot phase0.Root) (*phase0.Attestation, error)
}

AggregateAttestationProvider is the interface for providing aggregate attestations.

type AggregateAttestationsSubmitter 

type AggregateAttestationsSubmitter interface {
	// SubmitAggregateAttestations submits aggregate attestations.
	SubmitAggregateAttestations(ctx context.Context, aggregateAndProofs []*phase0.SignedAggregateAndProof) error
}

AggregateAttestationsSubmitter is the interface for submitting aggregate attestations.

type AttestationDataProvider 

type AttestationDataProvider interface {
	// AttestationData fetches the attestation data for the given slot and committee index.
	AttestationData(ctx context.Context, slot phase0.Slot, committeeIndex phase0.CommitteeIndex) (*phase0.AttestationData, error)
}

AttestationDataProvider is the interface for providing attestation data.

type AttestationPoolProvider added in v0.6.23 

type AttestationPoolProvider interface {
	// AttestationPool fetches the attestation pool for the given slot.
	AttestationPool(ctx context.Context, slot phase0.Slot) ([]*phase0.Attestation, error)
}

AttestationPoolProvider is the interface for providing attestation pools.

type AttestationsSubmitter added in v0.6.9 

type AttestationsSubmitter interface {
	// SubmitAttestations submits attestations.
	SubmitAttestations(ctx context.Context, attestations []*phase0.Attestation) error
}

AttestationsSubmitter is the interface for submitting attestations.

type AttesterDutiesProvider 

type AttesterDutiesProvider interface {
	// AttesterDuties obtains attester duties.
	// If validatorIndicess is nil it will return all duties for the given epoch.
	AttesterDuties(ctx context.Context, epoch phase0.Epoch, validatorIndices []phase0.ValidatorIndex) ([]*api.AttesterDuty, error)
}

AttesterDutiesProvider is the interface for providing attester duties

type BeaconBlockHeadersProvider added in v0.6.9 

type BeaconBlockHeadersProvider interface {
	// BeaconBlockHeader provides the block header of a given block ID.
	BeaconBlockHeader(ctx context.Context, blockID string) (*api.BeaconBlockHeader, error)
}

BeaconBlockHeadersProvider is the interface for providing beacon block headers.

type BeaconBlockProposalProvider 

type BeaconBlockProposalProvider interface {
	// BeaconBlockProposal fetches a proposed beacon block for signing.
	BeaconBlockProposal(ctx context.Context, slot phase0.Slot, randaoReveal phase0.BLSSignature, graffiti []byte) (*spec.VersionedBeaconBlock, error)
}

BeaconBlockProposalProvider is the interface for providing beacon block proposals.

type BeaconBlockRootProvider 

type BeaconBlockRootProvider interface {
	// BeaconBlockRoot fetches a block's root given a block ID.
	BeaconBlockRoot(ctx context.Context, blockID string) (*phase0.Root, error)
}

BeaconBlockRootProvider is the interface for providing beacon block roots.

type BeaconBlockSubmitter 

type BeaconBlockSubmitter interface {
	// SubmitBeaconBlock submits a beacon block.
	SubmitBeaconBlock(ctx context.Context, block *spec.VersionedSignedBeaconBlock) error
}

BeaconBlockSubmitter is the interface for submitting beacon blocks.

type BeaconChainHeadUpdatedHandler 

type BeaconChainHeadUpdatedHandler interface {
	// OnBeaconChainHeadUpdated is called whenever we receive a notification of an update to the beacon chain head.
	OnBeaconChainHeadUpdated(ctx context.Context, slot uint64, blockRoot []byte, stateRoot []byte, epochTransition bool)
}

BeaconChainHeadUpdatedHandler is the interface that needs to be implemented by processes that wish to receive beacon chain head updated messages.

type BeaconChainHeadUpdatedSource 

type BeaconChainHeadUpdatedSource interface {
	// AddOnBeaconChainHeadUpdatedHandler adds a handler provided with beacon chain head updates.
	AddOnBeaconChainHeadUpdatedHandler(ctx context.Context, handler BeaconChainHeadUpdatedHandler) error
}

BeaconChainHeadUpdatedSource is the interface for a service that provides beacon chain head updates.

type BeaconCommitteeSubscriptionsSubmitter 

type BeaconCommitteeSubscriptionsSubmitter interface {
	// SubmitBeaconCommitteeSubscriptions subscribes to beacon committees.
	SubmitBeaconCommitteeSubscriptions(ctx context.Context, subscriptions []*api.BeaconCommitteeSubscription) error
}

BeaconCommitteeSubscriptionsSubmitter is the interface for submitting beacon committee subnet subscription requests.

type BeaconCommitteesProvider 

type BeaconCommitteesProvider interface {
	// BeaconCommittees fetches all beacon committees for the epoch at the given state.
	BeaconCommittees(ctx context.Context, stateID string) ([]*api.BeaconCommittee, error)
}

BeaconCommitteesProvider is the interface for providing beacon committees.

type BeaconStateProvider added in v0.6.9 

type BeaconStateProvider interface {
	// BeaconState fetches a beacon state.
	BeaconState(ctx context.Context, stateID string) (*spec.VersionedBeaconState, error)
}

BeaconStateProvider is the interface for providing beacon state.

type DepositContractProvider 

type DepositContractProvider interface {
	// DepositContract provides the details of the deposit contract.
	DepositContract(ctx context.Context) (*api.DepositContract, error)
}

DepositContractProvider is the interface for providng details about the deposit contract.

type DomainProvider added in v0.6.9 

type DomainProvider interface {
	// Domain provides a domain for a given domain type at a given epoch.
	Domain(ctx context.Context, domainType phase0.DomainType, epoch phase0.Epoch) (phase0.Domain, error)
}

DomainProvider provides a domain for a given domain type at an epoch.

type EpochFromStateIDProvider added in v0.6.9 

type EpochFromStateIDProvider interface {
	// EpochFromStateID converts a state ID to its epoch.
	EpochFromStateID(ctx context.Context, stateID string) (phase0.Epoch, error)
}

EpochFromStateIDProvider is the interface for providing epochs from state IDs.

type EventHandlerFunc added in v0.6.9 

type EventHandlerFunc func(*api.Event)

EventHandlerFunc is the handler for events.

type EventsProvider added in v0.6.9 

type EventsProvider interface {
	// Events feeds requested events with the given topics to the supplied handler.
	Events(ctx context.Context, topics []string, handler EventHandlerFunc) error
}

EventsProvider is the interface for providing events.

type FarFutureEpochProvider added in v0.6.13 

type FarFutureEpochProvider interface {
	// FarFutureEpoch provides the far future epoch of the chain.
	FarFutureEpoch(ctx context.Context) (phase0.Epoch, error)
}

FarFutureEpochProvider is the interface for providing the far future epoch of a chain.

type FinalityProvider added in v0.6.10 

type FinalityProvider interface {
	// Finality provides the finality given a state ID.
	Finality(ctx context.Context, stateID string) (*api.Finality, error)
}

FinalityProvider is the interface for providing finality information.

type ForkProvider 

type ForkProvider interface {
	// Fork fetches fork information for the given state.
	Fork(ctx context.Context, stateID string) (*phase0.Fork, error)
}

ForkProvider is the interface for providing fork information.

type ForkScheduleProvider added in v0.6.5 

type ForkScheduleProvider interface {
	// ForkSchedule provides details of past and future changes in the chain's fork version.
	ForkSchedule(ctx context.Context) ([]*phase0.Fork, error)
}

ForkScheduleProvider is the interface for providing fork schedule data.

type GenesisProvider 

type GenesisProvider interface {
	// Genesis fetches genesis information for the chain.
	Genesis(ctx context.Context) (*api.Genesis, error)
}

GenesisProvider is the interface for providing genesis information.

type GenesisTimeProvider 

type GenesisTimeProvider interface {
	// GenesisTime provides the genesis time of the chain.
	GenesisTime(ctx context.Context) (time.Time, error)
}

GenesisTimeProvider is the interface for providing the genesis time of a chain.

type GenesisValidatorsRootProvider 

type GenesisValidatorsRootProvider interface {
	// GenesisValidatorsRoot provides the genesis validators root of the chain.
	GenesisValidatorsRoot(ctx context.Context) ([]byte, error)
}

GenesisValidatorsRootProvider is the interface for providing the genesis validators root of a chain.

type NodeSyncingProvider added in v0.6.9 

type NodeSyncingProvider interface {
	// NodeSyncing provides the state of the node's synchronization with the chain.
	NodeSyncing(ctx context.Context) (*api.SyncState, error)
}

NodeSyncingProvider is the interface for providing synchronization state.

type NodeVersionProvider 

type NodeVersionProvider interface {
	// NodeVersion returns a free-text string with the node version.
	NodeVersion(ctx context.Context) (string, error)
}

NodeVersionProvider is the interface for providing the node version.

type ProposerDutiesProvider 

type ProposerDutiesProvider interface {
	// ProposerDuties obtains proposer duties for the given epoch.
	// If validatorIndices is empty all duties are returned, otherwise only matching duties are returned.
	ProposerDuties(ctx context.Context, epoch phase0.Epoch, validatorIndices []phase0.ValidatorIndex) ([]*api.ProposerDuty, error)
}

ProposerDutiesProvider is the interface for providing proposer duties.

type PrysmAggregateAttestationProvider added in v0.6.9 

type PrysmAggregateAttestationProvider interface {
	// PrysmAggregateAttestation fetches the aggregate attestation given an attestation.
	PrysmAggregateAttestation(ctx context.Context, attestation *phase0.Attestation, validatorPubKey phase0.BLSPubKey, slotSignature phase0.BLSSignature) (*phase0.Attestation, error)
}

PrysmAggregateAttestationProvider is the interface for providing aggregate attestations.

type PrysmAttesterDutiesProvider added in v0.6.9 

type PrysmAttesterDutiesProvider interface {
	// PrysmAttesterDuties obtains attester duties with prysm-specific parameters.
	PrysmAttesterDuties(ctx context.Context, epoch phase0.Epoch, validatorPubKeys []phase0.BLSPubKey) ([]*api.AttesterDuty, error)
}

PrysmAttesterDutiesProvider is the interface for providing attester duties with prysm-specific parameters.

type PrysmProposerDutiesProvider added in v0.6.9 

type PrysmProposerDutiesProvider interface {
	// PrysmProposerDuties obtains proposer duties with prysm-specific parameters.
	PrysmProposerDuties(ctx context.Context, epoch phase0.Epoch, validatorPubKeys []phase0.BLSPubKey) ([]*api.ProposerDuty, error)
}

PrysmProposerDutiesProvider is the interface for providing proposer duties with prysm-specific parameters.

type PrysmValidatorBalancesProvider added in v0.6.9 

type PrysmValidatorBalancesProvider interface {
	// PrysmValidatorBalances provides the validator balances for a given state.
	// stateID can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
	// validatorIDs is a list of validator indices to restrict the returned values.  If no validators are supplied no filter
	// will be applied.
	PrysmValidatorBalances(ctx context.Context, stateID string, validatorPubKeys []phase0.BLSPubKey) (map[phase0.ValidatorIndex]phase0.Gwei, error)
}

PrysmValidatorBalancesProvider is the interface for providing validator balances.

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 Ethereum 2 client.

type SignedBeaconBlockProvider 

type SignedBeaconBlockProvider interface {
	// SignedBeaconBlock fetches a signed beacon block given a block ID.
	SignedBeaconBlock(ctx context.Context, blockID string) (*spec.VersionedSignedBeaconBlock, error)
}

SignedBeaconBlockProvider is the interface for providing beacon blocks.

type SlotDurationProvider 

type SlotDurationProvider interface {
	// SlotDuration provides the duration of a slot of the chain.
	SlotDuration(ctx context.Context) (time.Duration, error)
}

SlotDurationProvider is the interface for providing the duration of each slot of a chain.

type SlotFromStateIDProvider added in v0.6.9 

type SlotFromStateIDProvider interface {
	// SlotFromStateID converts a state ID to its slot.
	SlotFromStateID(ctx context.Context, stateID string) (phase0.Slot, error)
}

SlotFromStateIDProvider is the interface for providing slots from state IDs.

type SlotsPerEpochProvider 

type SlotsPerEpochProvider interface {
	// SlotsPerEpoch provides the slots per epoch of the chain.
	SlotsPerEpoch(ctx context.Context) (uint64, error)
}

SlotsPerEpochProvider is the interface for providing the number of slots in each epoch of a chain.

type SpecProvider added in v0.6.5 

type SpecProvider interface {
	// Spec provides the spec information of the chain.
	Spec(ctx context.Context) (map[string]interface{}, error)
}

SpecProvider is the interface for providing spec data.

type StateRootProvider added in v0.8.0 

type StateRootProvider interface {
	// StateRoot provides the state root given a state ID.
	StateRoot(ctx context.Context, stateID string) ([]byte, error)
}

StateRootProvider is the interface for providing state roots.

type SyncCommitteeContributionProvider added in v0.7.0 

type SyncCommitteeContributionProvider interface {
	// SyncCommitteeContribution provides a sync committee contribution.
	SyncCommitteeContribution(ctx context.Context, slot phase0.Slot, subcommitteeIndex uint64, beaconBlockRoot phase0.Root) (*altair.SyncCommitteeContribution, error)
}

SyncCommitteeContributionProvider is the interface for providing sync committee contributions.

type SyncCommitteeContributionsSubmitter added in v0.7.0 

type SyncCommitteeContributionsSubmitter interface {
	// SubmitSyncCommitteeContributions submits sync committee contributions.
	SubmitSyncCommitteeContributions(ctx context.Context, contributionAndProofs []*altair.SignedContributionAndProof) error
}

SyncCommitteeContributionsSubmitter is the interface for submitting sync committee contributions.

type SyncCommitteeDutiesProvider added in v0.7.0 

type SyncCommitteeDutiesProvider interface {
	// SyncCommitteesDuties obtains attester duties.
	// If validatorIndicess is nil it will return all duties for the given epoch.
	SyncCommitteeDuties(ctx context.Context, epoch phase0.Epoch, validatorIndices []phase0.ValidatorIndex) ([]*api.SyncCommitteeDuty, error)
}

SyncCommitteeDutiesProvider is the interface for providing sync committee duties.

type SyncCommitteeMessagesSubmitter added in v0.7.0 

type SyncCommitteeMessagesSubmitter interface {
	// SubmitSyncCommitteeMessages submits sync committee messages.
	SubmitSyncCommitteeMessages(ctx context.Context, messages []*altair.SyncCommitteeMessage) error
}

SyncCommitteeMessagesSubmitter is the interface for submitting sync committee messages.

type SyncCommitteeSubscriptionsSubmitter added in v0.7.0 

type SyncCommitteeSubscriptionsSubmitter interface {
	// SubmitSyncCommitteeSubscriptions subscribes to sync committees.
	SubmitSyncCommitteeSubscriptions(ctx context.Context, subscriptions []*api.SyncCommitteeSubscription) error
}

SyncCommitteeSubscriptionsSubmitter is the interface for submitting sync committee subnet subscription requests.

type SyncCommitteesProvider added in v0.7.0 

type SyncCommitteesProvider interface {
	// SyncCommittee fetches the sync committee for the given state.
	SyncCommittee(ctx context.Context, stateID string) (*api.SyncCommittee, error)
}

SyncCommitteesProvider is the interface for providing sync committees.

type SyncStateProvider 

type SyncStateProvider interface {
	// SyncState provides the state of the node's synchronization with the chain.
	SyncState(ctx context.Context) (*api.SyncState, error)
}

SyncStateProvider is the interface for providing synchronization state.

type TargetAggregatorsPerCommitteeProvider 

type TargetAggregatorsPerCommitteeProvider interface {
	// TargetAggregatorsPerCommittee provides the target number of aggregators for each attestation committee.
	TargetAggregatorsPerCommittee(ctx context.Context) (uint64, error)
}

TargetAggregatorsPerCommitteeProvider is the interface for providing the target number of aggregators in each attestation committee.

type ValidatorBalancesProvider 

type ValidatorBalancesProvider interface {
	// ValidatorBalances provides the validator balances for a given state.
	// stateID can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
	// validatorIndices is a list of validator indices to restrict the returned values.  If no validators are supplied no filter
	// will be applied.
	ValidatorBalances(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (map[phase0.ValidatorIndex]phase0.Gwei, error)
}

ValidatorBalancesProvider is the interface for providing validator balances.

type ValidatorIDProvider 

type ValidatorIDProvider interface {
	ValidatorIndexProvider
	ValidatorPubKeyProvider
}

ValidatorIDProvider is the interface that provides the identifiers (pubkey, index) of a validator.

type ValidatorIndexProvider 

type ValidatorIndexProvider interface {
	// Index provides the index of the validator.
	Index(ctx context.Context) (phase0.ValidatorIndex, error)
}

ValidatorIndexProvider is the interface for entities that can provide the index of a validator.

type ValidatorPubKeyProvider 

type ValidatorPubKeyProvider interface {
	// PubKey provides the public key of the validator.
	PubKey(ctx context.Context) (phase0.BLSPubKey, error)
}

ValidatorPubKeyProvider is the interface for entities that can provide the public key of a validator.

type ValidatorsProvider 

type ValidatorsProvider interface {
	// Validators provides the validators, with their balance and status, for a given state.
	// stateID can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
	// validatorIndices is a list of validator indices to restrict the returned values.  If no validators IDs are supplied no filter
	// will be applied.
	Validators(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (map[phase0.ValidatorIndex]*api.Validator, error)

	// ValidatorsByPubKey provides the validators, with their balance and status, for a given state.
	// stateID can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
	// validatorPubKeys is a list of validator public keys to restrict the returned values.  If no validators public keys are
	// supplied no filter will be applied.
	ValidatorsByPubKey(ctx context.Context, stateID string, validatorPubKeys []phase0.BLSPubKey) (map[phase0.ValidatorIndex]*api.Validator, error)
}

ValidatorsProvider is the interface for providing validator information.

type ValidatorsWithoutBalanceProvider added in v0.6.7 

type ValidatorsWithoutBalanceProvider interface {
	// ValidatorsWithoutBalance provides the validators, with their status, for a given state.
	// Balances are set to 0.
	// This is a non-standard call, only to be used if fetching balances results in the call being too slow.
	// stateID can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
	// validatorIndices is a list of validator indices to restrict the returned values.  If no validators IDs are supplied no filter
	// will be applied.
	ValidatorsWithoutBalance(ctx context.Context, stateID string, validatorIndices []phase0.ValidatorIndex) (map[phase0.ValidatorIndex]*api.Validator, error)

	// ValidatorsWithoutBalanceByPubKey provides the validators, with their status, for a given state.
	// This is a non-standard call, only to be used if fetching balances results in the call being too slow.
	// stateID can be a slot number or state root, or one of the special values "genesis", "head", "justified" or "finalized".
	// validatorPubKeys is a list of validator public keys to restrict the returned values.  If no validators public keys are
	// supplied no filter will be applied.
	ValidatorsWithoutBalanceByPubKey(ctx context.Context, stateID string, validatorPubKeys []phase0.BLSPubKey) (map[phase0.ValidatorIndex]*api.Validator, error)
}

ValidatorsWithoutBalanceProvider is the interface for providing validator information, minus the balance.

type VoluntaryExitSubmitter added in v0.6.10 

type VoluntaryExitSubmitter interface {
	// SubmitVoluntaryExit submits a voluntary exit.
	SubmitVoluntaryExit(ctx context.Context, voluntaryExit *phase0.SignedVoluntaryExit) error
}

VoluntaryExitSubmitter is the interface for submitting voluntary exits.

Source Files

View all Source files

Directories

Path Synopsis
api
v1
altair
Code generated by fastssz.
 Code generated by fastssz.
phase0
Code generated by fastssz.
 Code generated by fastssz.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.