sync

Documentation

Index

• Variables
• type Option
  • func WithBlockTime(duration time.Duration) Option
  • func WithMetrics() Option
  • func WithParams(params Parameters) Option
  • func WithPruningWindow(window time.Duration) Option
  • func WithRecencyThreshold(threshold time.Duration) Option
  • func WithSyncFromHash(hash string) Option
  • func WithSyncFromHeight(height uint64) Option
  • func WithTrustingPeriod(duration time.Duration) Option
• type Parameters
  • func DefaultParameters() Parameters
  • func (p *Parameters) Hash() (header.Hash, error)
  • 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[H]](getter header.Getter[H], store header.Store[H], sub header.Subscriber[H], ...) (*Syncer[H], error)
  • func (s *Syncer[H]) Head(ctx context.Context, _ ...header.HeadOption[H]) (H, 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

Variables

var NetworkHeadRequestTimeout = time.Second * 2

NetworkHeadRequestTimeout is the amount of time the syncer is willing to wait for the exchange to request the head of the chain from the network.

Types

type Option

type Option func(*Parameters)

Option is the functional option that is applied to the Syner instance to configure its parameters.

func WithBlockTime

func WithBlockTime(duration time.Duration) Option

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

func WithMetrics

func WithMetrics() Option

WithMetrics enables Metrics on Syncer.

func WithParams

func WithParams(params Parameters) Option

WithParams is a functional option that overrides Parameters.

func WithPruningWindow

func WithPruningWindow(window time.Duration) Option

WithPruningWindow sets the duration within which headers will be retained before being pruned.

func WithRecencyThreshold

func WithRecencyThreshold(threshold time.Duration) Option

WithRecencyThreshold is a functional option that configures the `recencyThreshold` parameter.

func WithSyncFromHash

func WithSyncFromHash(hash string) Option

WithSyncFromHash sets given header hash a starting point for syncing. See [Parameters.SyncFromHash] for details.

func WithSyncFromHeight

func WithSyncFromHeight(height uint64) Option

WithSyncFromHeight sets given height a starting point for syncing. See [Parameters.SyncFromHeight] for details.

func WithTrustingPeriod

func WithTrustingPeriod(duration time.Duration) Option

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

type Parameters

type Parameters struct {
	// PruningWindow defines the duration within which headers are retained before being pruned.
	PruningWindow time.Duration
	// SyncFromHash is the hash of the header from which Syncer should start syncing.
	// Zero value to disable. Value updates up and down the chain are gracefully handled by Syncer.
	//
	// By default, Syncer maintains PruningWindow number of headers. SyncFromHash overrides this default,
	// allowing any user to specify a custom starting point.
	//
	// SyncFromHash has higher priority than SyncFromHeight.
	SyncFromHash string
	// SyncFromHeight is the height of the header from which Syncer should start syncing.
	// Zero value to disable. Value updates up and down the chain are gracefully handled by Syncer.
	//
	// By default, Syncer maintains PruningWindow number of headers. SyncFromHeight overrides this default,
	// allowing any user to specify a custom starting point.
	//
	// SyncFromHeight has lower priority than SyncFromHash.
	SyncFromHeight uint64
	// 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) Hash

func (p *Parameters) Hash() (header.Hash, error)

func (*Parameters) Validate

func (p *Parameters) Validate() error

type State

type State struct {
	ID         uint64      `json:"id"`          // incrementing ID of a sync
	Height     uint64      `json:"height"`      // height at the moment when State is requested for a sync
	FromHeight uint64      `json:"from_height"` // the starting point of a sync
	ToHeight   uint64      `json:"to_height"`   // the ending point of a sync
	FromHash   header.Hash `json:"from_hash"`
	ToHash     header.Hash `json:"to_hash"`
	Start      time.Time   `json:"start"`
	End        time.Time   `json:"end"`
	Error      string      `json:"error,omitempty"` // 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[H]] 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[H]](
	getter header.Getter[H],
	store header.Store[H],
	sub header.Subscriber[H],
	opts ...Option,
) (*Syncer[H], error)

NewSyncer creates a new instance of Syncer.

func (*Syncer[H]) Head

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

Head returns the most recent network head header.

It will try to get the most recent network head or return the current non-expired subjective head as a fallback. If the head has changed, it will update the tail with the new head.

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.