sync

Documentation

Index

• type Options
  • func WithBlockTime(duration time.Duration) Options
  • func WithTrustingPeriod(duration time.Duration) Options
• type Parameters
  • func DefaultParameters() Parameters
  • func (p *Parameters) Validate() error
• type State
  • func (s State) Duration() time.Duration
  • func (s State) Finished() bool
• type Syncer
  • func NewSyncer[H header.Header](getter header.Getter[H], store header.Store[H], sub header.Subscriber[H], ...) (*Syncer[H], error)
  • func (s *Syncer[H]) Head(ctx context.Context) (H, error)
  • func (s *Syncer[H]) InitMetrics() error
  • func (s *Syncer[H]) Start(ctx context.Context) error
  • func (s *Syncer[H]) State() State
  • func (s *Syncer[H]) Stop(context.Context) error
  • func (s *Syncer[H]) SyncWait(ctx context.Context) error

Types

type Options

type Options func(*Parameters)

func WithBlockTime

func WithBlockTime(duration time.Duration) Options

WithBlockTime is a functional option that configures the `blockTime` parameter.

func WithTrustingPeriod

func WithTrustingPeriod(duration time.Duration) Options

WithTrustingPeriod is a functional option that configures the `TrustingPeriod` parameter.

type Parameters

type Parameters struct {
	// TrustingPeriod is period through which we can trust a header's validators set.
	//
	// Should be significantly less than the unbonding period (e.g. unbonding
	// period = 3 weeks, trusting period = 2 weeks).
	//
	// More specifically, trusting period + time needed to check headers + time
	// needed to report and punish misbehavior should be less than the unbonding
	// period.
	TrustingPeriod time.Duration
	// contains filtered or unexported fields
}

Parameters is the set of parameters that must be configured for the syncer.

func DefaultParameters

func DefaultParameters() Parameters

DefaultParameters returns the default params to configure the syncer.

func (*Parameters) Validate

func (p *Parameters) Validate() error

type State

type State struct {
	ID                   uint64 // incrementing ID of a sync
	Height               uint64 // height at the moment when State is requested for a sync
	FromHeight, ToHeight uint64 // the starting and the ending point of a sync
	FromHash, ToHash     header.Hash
	Start, End           time.Time
	Error                error // the error that might happen within a sync
}

State collects all the information about a sync.

func (State) Duration

func (s State) Duration() time.Duration

Duration returns the duration of the sync.

func (State) Finished

func (s State) Finished() bool

Finished returns true if sync is done, false otherwise.

type Syncer

type Syncer[H header.Header] struct {
	Params *Parameters
	// contains filtered or unexported fields
}

Syncer implements efficient synchronization for headers.

Subjective Head - the latest known local valid header and a sync target. Network Head - the latest valid network-wide header. Becomes subjective once applied locally.

There are two main processes running in Syncer: - Main syncing loop(s.syncLoop)

• Performs syncing from the latest stored header up to the latest known Subjective Head
• Syncs by requesting missing headers from Exchange or
• By accessing cache of pending headers

- Receives every new Network Head from PubSub gossip subnetwork (s.incomingNetworkHead)

• Validates against the latest known Subjective Head, is so
• Sets as the new Subjective Head, which
• if there is a gap between the previous and the new Subjective Head
• Triggers s.syncLoop and saves the Subjective Head in the pending so s.syncLoop can access it

func NewSyncer

func NewSyncer[H header.Header](
	getter header.Getter[H],
	store header.Store[H],
	sub header.Subscriber[H],
	opts ...Options,
) (*Syncer[H], error)

NewSyncer creates a new instance of Syncer.

func (*Syncer[H]) Head

func (s *Syncer[H]) Head(ctx context.Context) (H, error)

Head returns the Network Head.

Known subjective head is considered network head if it is recent enough(now-timestamp<=blocktime) Otherwise, head is requested from a trusted peer and set as the new subjective head, assuming that trusted peer is always fully synced.

func (*Syncer[H]) InitMetrics

func (s *Syncer[H]) InitMetrics() error

func (*Syncer[H]) Start

func (s *Syncer[H]) Start(ctx context.Context) error

Start starts the syncing routine.

func (*Syncer[H]) State

func (s *Syncer[H]) State() State

State reports state of the current (if in progress), or last sync (if finished). Note that throughout the whole Syncer lifetime there might an initial sync and multiple catch-ups. All of them are treated as different syncs with different state IDs and other information.

func (*Syncer[H]) Stop

func (s *Syncer[H]) Stop(context.Context) error

Stop stops Syncer.

func (*Syncer[H]) SyncWait

func (s *Syncer[H]) SyncWait(ctx context.Context) error

SyncWait blocks until ongoing sync is done.