core

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Jul 7, 2022 License: GPL-3.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DutyToProto added in v0.3.0 

func DutyToProto(duty Duty) *pbv1.Duty

DutyToProto returns the duty as a protobuf.

func NewDutyDeadlineFunc added in v0.6.0 

func NewDutyDeadlineFunc(ctx context.Context, eth2Svc eth2client.Service) (func(Duty) time.Time, error)

NewDutyDeadlineFunc returns the function that provides duty deadlines.

func ParSignedDataSetToProto added in v0.3.0 

func ParSignedDataSetToProto(set ParSignedDataSet) (*pbv1.ParSignedDataSet, error)

ParSignedDataSetToProto returns the set as a protobuf.

func ParSignedDataToProto added in v0.3.0 

func ParSignedDataToProto(data ParSignedData) (*pbv1.ParSignedData, error)

ParSignedDataToProto returns the data as a protobuf.

func StartDutyTrace 

func StartDutyTrace(ctx context.Context, duty Duty, spanName string, opts ...trace.SpanStartOption) (context.Context, trace.Span)

StartDutyTrace returns a context and span rooted to the duty traceID and wrapped in a duty span. This creates a new trace root and should generally only be called when a new duty is scheduled or when a duty is received from the VC or peer.

func UnsignedDataSetToProto added in v0.4.0 

func UnsignedDataSetToProto(set UnsignedDataSet) (*pbv1.UnsignedDataSet, error)

UnsignedDataSetToProto returns the set as a protobuf.

func Wire 

func Wire(sched Scheduler,
	fetch Fetcher,
	cons Consensus,
	dutyDB DutyDB,
	vapi ValidatorAPI,
	parSigDB ParSigDB,
	parSigEx ParSigEx,
	sigAgg SigAgg,
	aggSigDB AggSigDB,
	bcast Broadcaster,
	opts ...WireOption,
)

Wire wires the workflow components together.

Types

type AggSigDB 

type AggSigDB interface {
	// Store stores aggregated signed duty data.
	Store(context.Context, Duty, PubKey, SignedData) error

	// Await blocks and returns the aggregated signed duty data when available.
	Await(context.Context, Duty, PubKey) (SignedData, error)
}

AggSigDB persists aggregated signed duty data.

type Attestation added in v0.7.0 

type Attestation struct {
	eth2p0.Attestation
}

Attestation is a signed attestation and implements SignedData.

func NewAttestation added in v0.7.0 

func NewAttestation(att *eth2p0.Attestation) Attestation

NewAttestation is a convenience function that returns a new wrapped attestation.

func (Attestation) Clone added in v0.7.0 

func (a Attestation) Clone() (SignedData, error)

func (Attestation) MarshalJSON added in v0.7.0 

func (a Attestation) MarshalJSON() ([]byte, error)

func (Attestation) SetSignature added in v0.7.0 

func (a Attestation) SetSignature(sig Signature) (SignedData, error)

func (Attestation) Signature added in v0.7.0 

func (a Attestation) Signature() Signature

func (*Attestation) UnmarshalJSON added in v0.7.0 

func (a *Attestation) UnmarshalJSON(b []byte) error

type AttestationData 

type AttestationData struct {
	Data eth2p0.AttestationData
	Duty eth2v1.AttesterDuty
}

AttestationData wraps the eth2 attestation data and adds the original duty. The original duty allows mapping the partial signed response from the VC backed to the validator pubkey via the aggregation bits field.

func (AttestationData) Clone added in v0.7.0 

func (a AttestationData) Clone() (UnsignedData, error)

func (AttestationData) MarshalJSON added in v0.7.0 

func (a AttestationData) MarshalJSON() ([]byte, error)

func (*AttestationData) UnmarshalJSON added in v0.7.0 

func (a *AttestationData) UnmarshalJSON(data []byte) error

type AttesterDefinition added in v0.7.0 

type AttesterDefinition struct {
	eth2v1.AttesterDuty
}

AttesterDefinition defines an attester duty. It implements DutyDefinition. Note the slight rename from Duty to Definition to avoid overloading the term Duty.

func NewAttesterDefinition added in v0.7.0 

func NewAttesterDefinition(duty *eth2v1.AttesterDuty) AttesterDefinition

NewAttesterDefinition is a convenience function that returns a new attester definition.

func (AttesterDefinition) Clone added in v0.7.0 

func (d AttesterDefinition) Clone() (DutyDefinition, error)

func (AttesterDefinition) MarshalJSON added in v0.7.0 

func (d AttesterDefinition) MarshalJSON() ([]byte, error)

type Broadcaster 

type Broadcaster interface {
	Broadcast(context.Context, Duty, PubKey, SignedData) error
}

Broadcaster broadcasts aggregated signed duty data to the beacon node.

type Consensus 

type Consensus interface {
	// Propose triggers consensus game of the proposed duty unsigned data set.
	Propose(context.Context, Duty, UnsignedDataSet) error

	// Subscribe registers a callback for resolved (reached consensus) duty unsigned data set.
	Subscribe(func(context.Context, Duty, UnsignedDataSet) error)
}

Consensus comes to consensus on proposed duty data.

type Duty 

type Duty struct {
	// Slot is the Ethereum consensus layer slot.
	Slot int64
	// Type is the duty type performed in the slot.
	Type DutyType
}

Duty is the unit of work of the core workflow.

func DutyFromProto added in v0.3.0 

func DutyFromProto(duty *pbv1.Duty) Duty

DutyFromProto returns the duty from a protobuf.

func NewAttesterDuty 

func NewAttesterDuty(slot int64) Duty

NewAttesterDuty returns a new attester duty. It is a convenience function that is slightly more readable and concise than the struct literal equivalent: 

core.Duty{Slot: slot, Type: core.DutyAttester}
vs
core.NewAttesterDuty(slot)

func NewProposerDuty added in v0.3.0 

func NewProposerDuty(slot int64) Duty

NewProposerDuty returns a new proposer duty. It is a convenience function that is slightly more readable and concise than the struct literal equivalent: 

core.Duty{Slot: slot, Type: core.DutyProposer}
vs
core.NewProposerDuty(slot)

func NewRandaoDuty added in v0.3.0 

func NewRandaoDuty(slot int64) Duty

NewRandaoDuty returns a new randao duty. It is a convenience function that is slightly more readable and concise than the struct literal equivalent: 

core.Duty{Slot: slot, Type: core.DutyRandao}
vs
core.NewRandaoDuty(slot)

func (Duty) String 

func (d Duty) String() string

type DutyDB 

type DutyDB interface {
	// Store stores the unsigned duty data set.
	Store(context.Context, Duty, UnsignedDataSet) error

	// AwaitBeaconBlock blocks and returns the proposed beacon block
	// for the slot when available.
	AwaitBeaconBlock(ctx context.Context, slot int64) (*spec.VersionedBeaconBlock, error)

	// AwaitAttestation blocks and returns the attestation data
	// for the slot and committee index when available.
	AwaitAttestation(ctx context.Context, slot, commIdx int64) (*eth2p0.AttestationData, error)

	// PubKeyByAttestation returns the validator PubKey for the provided attestation data
	// slot, committee index and validator committee index. This allows mapping of attestation
	// data response to validator.
	PubKeyByAttestation(ctx context.Context, slot, commIdx, valCommIdx int64) (PubKey, error)
}

DutyDB persists unsigned duty data sets and makes it available for querying. It also acts as slashing database.

type DutyDefinition added in v0.7.0 

type DutyDefinition interface {
	// Clone returns a cloned copy of the DutyDefinition.
	Clone() (DutyDefinition, error)
	// Marshaler returns the json serialised duty definition.
	json.Marshaler
}

DutyDefinition defines the duty including parameters required to fetch the duty data, it is the result of resolving duties at the start of an epoch.

type DutyDefinitionSet added in v0.7.0 

type DutyDefinitionSet map[PubKey]DutyDefinition

DutyDefinitionSet is a set of duty definitions, one per validator.

func (DutyDefinitionSet) Clone added in v0.7.0 

func (s DutyDefinitionSet) Clone() (DutyDefinitionSet, error)

Clone returns a cloned copy of the DutyDefinitionSet. For an immutable core workflow architecture, remember to clone data when it leaves the current scope (sharing, storing, returning, etc).

type DutyType 

type DutyType int

DutyType enumerates the different types of duties. 

const (
	DutyUnknown  DutyType = 0
	DutyProposer DutyType = 1
	DutyAttester DutyType = 2
	DutyRandao   DutyType = 3
	DutyExit     DutyType = 4
)

func AllDutyTypes 

func AllDutyTypes() []DutyType

AllDutyTypes returns a list of all valid duty types.

func (DutyType) String 

func (d DutyType) String() string

func (DutyType) Valid 

func (d DutyType) Valid() bool

type Fetcher 

type Fetcher interface {
	// Fetch triggers fetching of a proposed duty data set.
	Fetch(context.Context, Duty, DutyDefinitionSet) error

	// Subscribe registers a callback for proposed unsigned duty data sets.
	Subscribe(func(context.Context, Duty, UnsignedDataSet) error)

	// RegisterAggSigDB registers a function to get resolved aggregated
	// signed data from the AggSigDB (e.g., randao reveals).
	RegisterAggSigDB(func(context.Context, Duty, PubKey) (SignedData, error))
}

Fetcher fetches proposed unsigned duty data.

type ParSigDB 

type ParSigDB interface {
	// StoreInternal stores an internally received partially signed duty data set.
	StoreInternal(context.Context, Duty, ParSignedDataSet) error

	// StoreExternal stores an externally received partially signed duty data set.
	StoreExternal(context.Context, Duty, ParSignedDataSet) error

	// SubscribeInternal registers a callback when an internal
	// partially signed duty set is stored.
	SubscribeInternal(func(context.Context, Duty, ParSignedDataSet) error)

	// SubscribeThreshold registers a callback when *threshold*
	// partially signed duty is reached for a DV.
	SubscribeThreshold(func(context.Context, Duty, PubKey, []ParSignedData) error)
}

ParSigDB persists partial signatures and sends them to the partial signature exchange and aggregation.

type ParSigEx 

type ParSigEx interface {
	// Broadcast broadcasts the partially signed duty data set to all peers.
	Broadcast(context.Context, Duty, ParSignedDataSet) error

	// Subscribe registers a callback when a partially signed duty set
	// is received from a peer.
	Subscribe(func(context.Context, Duty, ParSignedDataSet) error)
}

ParSigEx exchanges partially signed duty data sets.

type ParSignedData 

type ParSignedData struct {
	// SignedData is a partially signed duty data.
	SignedData
	// ShareIdx returns the threshold BLS share index.
	ShareIdx int
}

ParSignedData is a partially signed duty data only signed by a single threshold BLS share.

func NewPartialAttestation added in v0.7.0 

func NewPartialAttestation(att *eth2p0.Attestation, shareIdx int) ParSignedData

NewPartialAttestation is a convenience function that returns a new partially signed attestation.

func NewPartialSignature added in v0.7.0 

func NewPartialSignature(sig Signature, shareIdx int) ParSignedData

NewPartialSignature is a convenience function that returns a new partially signature.

func NewPartialSignedVoluntaryExit added in v0.7.0 

func NewPartialSignedVoluntaryExit(exit *eth2p0.SignedVoluntaryExit, shareIdx int) ParSignedData

NewPartialSignedVoluntaryExit is a convenience function that returns a new partially signed voluntary exit.

func NewPartialVersionedSignedBeaconBlock added in v0.7.0 

func NewPartialVersionedSignedBeaconBlock(block *spec.VersionedSignedBeaconBlock, shareIdx int) (ParSignedData, error)

NewPartialVersionedSignedBeaconBlock is a convenience function that returns a new partial signed block.

func ParSignedDataFromProto added in v0.3.0 

func ParSignedDataFromProto(typ DutyType, data *pbv1.ParSignedData) (ParSignedData, error)

ParSignedDataFromProto returns the data from a protobuf.

func (ParSignedData) Clone added in v0.7.0 

func (d ParSignedData) Clone() (ParSignedData, error)

Clone returns a cloned copy of the ParSignedData. For an immutable core workflow architecture, remember to clone data when it leaves the current scope (sharing, storing, returning, etc).

type ParSignedDataSet 

type ParSignedDataSet map[PubKey]ParSignedData

ParSignedDataSet is a set of partially signed duty data objects, one per validator.

func ParSignedDataSetFromProto added in v0.3.0 

func ParSignedDataSetFromProto(typ DutyType, set *pbv1.ParSignedDataSet) (ParSignedDataSet, error)

ParSignedDataSetFromProto returns the set from a protobuf.

func (ParSignedDataSet) Clone added in v0.7.0 

func (s ParSignedDataSet) Clone() (ParSignedDataSet, error)

Clone returns a cloned copy of the ParSignedDataSet. For an immutable core workflow architecture, remember to clone data when it leaves the current scope (sharing, storing, returning, etc).

type ProposerDefinition added in v0.7.0 

type ProposerDefinition struct {
	eth2v1.ProposerDuty
}

ProposerDefinition defines a block proposer duty. It implements DutyDefinition. Note the slight rename from Duty to Definition to avoid overloading the term Duty.

func NewProposerDefinition added in v0.7.0 

func NewProposerDefinition(duty *eth2v1.ProposerDuty) ProposerDefinition

NewProposerDefinition is a convenience function that returns a new proposer definition.

func (ProposerDefinition) Clone added in v0.7.0 

func (d ProposerDefinition) Clone() (DutyDefinition, error)

func (ProposerDefinition) MarshalJSON added in v0.7.0 

func (d ProposerDefinition) MarshalJSON() ([]byte, error)

type PubKey 

type PubKey string

PubKey is the DV root public key, the identifier of a validator in the core workflow. It is a hex formatted string, e.g. "0xb82bc680e...".

func PubKeyFromBytes 

func PubKeyFromBytes(bytes []byte) (PubKey, error)

PubKeyFromBytes returns a new public key from raw bytes.

func (PubKey) Bytes 

func (k PubKey) Bytes() ([]byte, error)

Bytes returns the public key as raw bytes.

func (PubKey) String 

func (k PubKey) String() string

String returns a concise logging friendly version of the public key, e.g. "b82_97f".

func (PubKey) ToETH2 

func (k PubKey) ToETH2() (eth2p0.BLSPubKey, error)

ToETH2 returns the public key as an eth2 phase0 public key.

type Scheduler 

type Scheduler interface {
	// Subscribe registers a callback for fetching a duty.
	Subscribe(func(context.Context, Duty, DutyDefinitionSet) error)

	// GetDutyDefinition returns the definition set for a duty if already resolved.
	GetDutyDefinition(context.Context, Duty) (DutyDefinitionSet, error)
}

Scheduler triggers the start of a duty workflow.

type SigAgg 

type SigAgg interface {
	// Aggregate aggregates the partially signed duty data for the DV.
	Aggregate(context.Context, Duty, PubKey, []ParSignedData) error

	// Subscribe registers a callback for aggregated signed duty data.
	Subscribe(func(context.Context, Duty, PubKey, SignedData) error)
}

SigAgg aggregates threshold partial signatures.

type Signature 

type Signature []byte

Signature is a BLS12-381 Signature. It implements SignedData.

func SigFromETH2 

func SigFromETH2(sig eth2p0.BLSSignature) Signature

SigFromETH2 returns a new signature from eth2 phase0 BLSSignature.

func (Signature) Clone added in v0.7.0 

func (s Signature) Clone() (SignedData, error)

func (Signature) MarshalJSON added in v0.7.0 

func (s Signature) MarshalJSON() ([]byte, error)

func (Signature) SetSignature added in v0.7.0 

func (Signature) SetSignature(sig Signature) (SignedData, error)

func (Signature) Signature added in v0.7.0 

func (s Signature) Signature() Signature

func (Signature) ToETH2 

func (s Signature) ToETH2() eth2p0.BLSSignature

ToETH2 returns the signature as an eth2 phase0 BLSSignature.

func (*Signature) UnmarshalJSON added in v0.7.0 

func (s *Signature) UnmarshalJSON(b []byte) error

type SignedData added in v0.7.0 

type SignedData interface {
	// Signature returns the signed duty data's signature.
	Signature() Signature
	// SetSignature returns a copy of signed duty data with the signature replaced.
	SetSignature(Signature) (SignedData, error)
	// Clone returns a cloned copy of the SignedData. For an immutable core workflow architecture,
	// remember to clone data when it leaves the current scope (sharing, storing, returning, etc).
	Clone() (SignedData, error)
	// Marshaler returns the json serialised signed duty data (including the signature).
	json.Marshaler
}

SignedData is a signed duty data.

type SignedVoluntaryExit added in v0.7.0 

type SignedVoluntaryExit struct {
	eth2p0.SignedVoluntaryExit
}

func NewSignedVoluntaryExit added in v0.7.0 

func NewSignedVoluntaryExit(exit *eth2p0.SignedVoluntaryExit) SignedVoluntaryExit

NewSignedVoluntaryExit is a convenience function that returns a new signed voluntary exit.

func (SignedVoluntaryExit) Clone added in v0.7.0 

func (e SignedVoluntaryExit) Clone() (SignedData, error)

func (SignedVoluntaryExit) MarshalJSON added in v0.7.0 

func (e SignedVoluntaryExit) MarshalJSON() ([]byte, error)

func (SignedVoluntaryExit) SetSignature added in v0.7.0 

func (e SignedVoluntaryExit) SetSignature(sig Signature) (SignedData, error)

func (SignedVoluntaryExit) Signature added in v0.7.0 

func (e SignedVoluntaryExit) Signature() Signature

func (*SignedVoluntaryExit) UnmarshalJSON added in v0.7.0 

func (e *SignedVoluntaryExit) UnmarshalJSON(b []byte) error

type UnsignedData 

type UnsignedData interface {
	// Clone returns a cloned copy of the UnsignedData. For an immutable core workflow architecture,
	// remember to clone data when it leaves the current scope (sharing, storing, returning, etc).
	Clone() (UnsignedData, error)
	// Marshaler returns the json serialised unsigned duty data.
	json.Marshaler
}

UnsignedData represents an unsigned duty data object.

func UnmarshalUnsignedData added in v0.7.0 

func UnmarshalUnsignedData(typ DutyType, data []byte) (UnsignedData, error)

UnmarshalUnsignedData returns an instantiated unsigned data based on the duty type. TODO(corver): Unexport once leadercast is removed or uses protobufs.

type UnsignedDataSet 

type UnsignedDataSet map[PubKey]UnsignedData

UnsignedDataSet is a set of unsigned duty data objects, one per validator.

func UnsignedDataSetFromProto added in v0.4.0 

func UnsignedDataSetFromProto(typ DutyType, set *pbv1.UnsignedDataSet) (UnsignedDataSet, error)

UnsignedDataSetFromProto returns the set from a protobuf.

func (UnsignedDataSet) Clone added in v0.7.0 

func (s UnsignedDataSet) Clone() (UnsignedDataSet, error)

Clone returns a cloned copy of the UnsignedDataSet. For an immutable core workflow architecture, remember to clone data when it leaves the current scope (sharing, storing, returning, etc).

type ValidatorAPI 

type ValidatorAPI interface {
	// RegisterAwaitBeaconBlock registers a function to query a unsigned beacon block by slot.
	RegisterAwaitBeaconBlock(func(ctx context.Context, slot int64) (*spec.VersionedBeaconBlock, error))

	// RegisterAwaitAttestation registers a function to query attestation data.
	RegisterAwaitAttestation(func(ctx context.Context, slot, commIdx int64) (*eth2p0.AttestationData, error))

	// RegisterPubKeyByAttestation registers a function to query validator by attestation.
	RegisterPubKeyByAttestation(func(ctx context.Context, slot, commIdx, valCommIdx int64) (PubKey, error))

	// RegisterGetDutyDefinition registers a function to query duty definitions.
	RegisterGetDutyDefinition(func(context.Context, Duty) (DutyDefinitionSet, error))

	// RegisterParSigDB registers a function to store partially signed data sets.
	RegisterParSigDB(func(context.Context, Duty, ParSignedDataSet) error)
}

ValidatorAPI provides a beacon node API to validator clients. It serves duty data from the DutyDB and stores partial signed data in the ParSigDB.

type VersionedBeaconBlock added in v0.7.0 

type VersionedBeaconBlock struct {
	spec.VersionedBeaconBlock
}

func NewVersionedBeaconBlock added in v0.7.0 

func NewVersionedBeaconBlock(block *spec.VersionedBeaconBlock) (VersionedBeaconBlock, error)

NewVersionedBeaconBlock validates and returns a new wrapped VersionedBeaconBlock.

func (VersionedBeaconBlock) Clone added in v0.7.0 

func (b VersionedBeaconBlock) Clone() (UnsignedData, error)

func (VersionedBeaconBlock) MarshalJSON added in v0.7.0 

func (b VersionedBeaconBlock) MarshalJSON() ([]byte, error)

func (*VersionedBeaconBlock) UnmarshalJSON added in v0.7.0 

func (b *VersionedBeaconBlock) UnmarshalJSON(input []byte) error

type VersionedSignedBeaconBlock added in v0.7.0 

type VersionedSignedBeaconBlock struct {
	spec.VersionedSignedBeaconBlock // Could subtype instead of embed, but aligning with Attestation that cannot subtype.
}

VersionedSignedBeaconBlock is a signed versioned beacon block and implements SignedData.

func NewVersionedSignedBeaconBlock added in v0.7.0 

func NewVersionedSignedBeaconBlock(block *spec.VersionedSignedBeaconBlock) (VersionedSignedBeaconBlock, error)

NewVersionedSignedBeaconBlock validates and returns a new wrapped VersionedSignedBeaconBlock.

func (VersionedSignedBeaconBlock) Clone added in v0.7.0 

func (b VersionedSignedBeaconBlock) Clone() (SignedData, error)

func (VersionedSignedBeaconBlock) MarshalJSON added in v0.7.0 

func (b VersionedSignedBeaconBlock) MarshalJSON() ([]byte, error)

func (VersionedSignedBeaconBlock) SetSignature added in v0.7.0 

func (b VersionedSignedBeaconBlock) SetSignature(sig Signature) (SignedData, error)

func (VersionedSignedBeaconBlock) Signature added in v0.7.0 

func (b VersionedSignedBeaconBlock) Signature() Signature

func (*VersionedSignedBeaconBlock) UnmarshalJSON added in v0.7.0 

func (b *VersionedSignedBeaconBlock) UnmarshalJSON(input []byte) error

type WireOption 

type WireOption func(*wireFuncs)

WireOption defines a functional option to configure wiring.

func WithAsyncRetry added in v0.3.0 

func WithAsyncRetry(retryer *retry.Retryer[Duty]) WireOption

WithAsyncRetry wraps component input functions with the async Retryer adding robustness to network issues.

func WithTracing 

func WithTracing() WireOption

WithTracing wraps component input functions with tracing spans.

Source Files

View all Source files

Directories

Path Synopsis
Package bcast provides the core workflow's broadcaster component that broadcasts/submits aggregated singed duty data to the beacon-node.
 Package bcast provides the core workflow's broadcaster component that broadcasts/submits aggregated singed duty data to the beacon-node.
corepb
v1
Package qbft is an implementation of the https://arxiv.org/pdf/2002.03613.pdf paper referenced by the QBFT spec https://github.com/ConsenSys/qbft-formal-spec-and-verification.
 Package qbft is an implementation of the https://arxiv.org/pdf/2002.03613.pdf paper referenced by the QBFT spec https://github.com/ConsenSys/qbft-formal-spec-and-verification.
Package sigagg provides the sigagg core workflow component that aggregates *threshold* partial signed duty data objects into an aggregated signed duty data object ready to be broadcasted to the beacon chain.
 Package sigagg provides the sigagg core workflow component that aggregates *threshold* partial signed duty data objects into an aggregated signed duty data object ready to be broadcasted to the beacon chain.
Package validatorapi defines validator facing API that serves the subset of endpoints related to distributed validation and reverse-proxies the rest to the upstream beacon client.
 Package validatorapi defines validator facing API that serves the subset of endpoints related to distributed validation and reverse-proxies the rest to the upstream beacon client.

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.