chainsync

package
v0.125.1 Latest Latest
Warning

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

 Go to latest Published: Jun 14, 2025 License: Apache-2.0 Imports: 10 Imported by: 15

Documentation

Overview

Package chainsync implements the Ouroboros chain-sync protocol

Index

Constants

View Source 
const (
	ProtocolName         = "chain-sync"
	ProtocolIdNtN uint16 = 2
	ProtocolIdNtC uint16 = 5
)

Protocol identifiers

View Source 
const (
	MessageTypeRequestNext       = 0
	MessageTypeAwaitReply        = 1
	MessageTypeRollForward       = 2
	MessageTypeRollBackward      = 3
	MessageTypeFindIntersect     = 4
	MessageTypeIntersectFound    = 5
	MessageTypeIntersectNotFound = 6
	MessageTypeDone              = 7
)

Message types

Variables

View Source 
var DecrementPipelineCountAndIsEmpty = func(context any, msg protocol.Message) bool {
	s := context.(*StateContext)
	s.mu.Lock()
	defer s.mu.Unlock()

	if s.pipelineCount == 1 {
		s.pipelineCount--
		return true
	}
	return false
}
View Source 
var DecrementPipelineCountAndIsNotEmpty = func(context any, msg protocol.Message) bool {
	s := context.(*StateContext)
	s.mu.Lock()
	defer s.mu.Unlock()

	if s.pipelineCount > 1 {
		s.pipelineCount--
		return true
	}
	return false
}
View Source 
var ErrIntersectNotFound = errors.New("chain intersection not found")
View Source 
var ErrStopSyncProcess = errors.New("stop sync process")

StopChainSync is used as a special return value from a RollForward or RollBackward handler function to signify that the sync process should be stopped

View Source 
var IncrementPipelineCount = func(context any, msg protocol.Message) bool {
	s := context.(*StateContext)
	s.mu.Lock()
	defer s.mu.Unlock()

	s.pipelineCount++
	return true
}
View Source 
var PipelineIsEmtpy = func(context any, msg protocol.Message) bool {
	s := context.(*StateContext)
	s.mu.Lock()
	defer s.mu.Unlock()

	return s.pipelineCount == 0
}
View Source 
var PipelineIsNotEmpty = func(context any, msg protocol.Message) bool {
	s := context.(*StateContext)
	s.mu.Lock()
	defer s.mu.Unlock()

	return s.pipelineCount > 0
}
View Source 
var StateMap = protocol.StateMap{
	// contains filtered or unexported fields
}

ChainSync protocol state machine

Functions

func NewMsgFromCbor 

func NewMsgFromCbor(
	protoMode protocol.ProtocolMode,
	msgType uint,
	data []byte,
) (protocol.Message, error)

NewMsgFromCbor parses a ChainSync message from CBOR

func NewMsgFromCborNtC 

func NewMsgFromCborNtC(msgType uint, data []byte) (protocol.Message, error)

NewMsgFromCborNtC parses a NtC ChainSync message from CBOR

func NewMsgFromCborNtN 

func NewMsgFromCborNtN(msgType uint, data []byte) (protocol.Message, error)

NewMsgFromCborNtN parses a NtC ChainSync message from CBOR

Types

type CallbackContext added in v0.78.0 

type CallbackContext struct {
	ConnectionId connection.ConnectionId
	Client       *Client
	Server       *Server
}

Callback context

type ChainSync 

type ChainSync struct {
	Client *Client
	Server *Server
}

ChainSync is a wrapper object that holds the client and server instances

func New 

func New(protoOptions protocol.ProtocolOptions, cfg *Config) *ChainSync

New returns a new ChainSync object

type ChainSyncOptionFunc 

type ChainSyncOptionFunc func(*Config)

ChainSyncOptionFunc represents a function used to modify the ChainSync protocol config

func WithBlockTimeout 

func WithBlockTimeout(timeout time.Duration) ChainSyncOptionFunc

WithBlockTimeout specifies the timeout for block fetch operations

func WithFindIntersectFunc added in v0.66.0 

func WithFindIntersectFunc(
	findIntersectFunc FindIntersectFunc,
) ChainSyncOptionFunc

WithFindIntersectFunc specifies the FindIntersect callback function

func WithIntersectTimeout 

func WithIntersectTimeout(timeout time.Duration) ChainSyncOptionFunc

WithIntersectTimeout specifies the timeout for intersect operations

func WithPipelineLimit added in v0.36.0 

func WithPipelineLimit(limit int) ChainSyncOptionFunc

WithPipelineLimit specifies the maximum number of block requests to pipeline

func WithRecvQueueSize added in v0.114.0 

func WithRecvQueueSize(size int) ChainSyncOptionFunc

WithRecvQueueSize specifies the size of the received messages queue. This is useful to adjust the number of pipelined messages that can be supported when acting as a server

func WithRequestNextFunc added in v0.66.0 

func WithRequestNextFunc(requestNextFunc RequestNextFunc) ChainSyncOptionFunc

WithRequestNextFunc specifies the RequestNext callback function

func WithRollBackwardFunc 

func WithRollBackwardFunc(
	rollBackwardFunc RollBackwardFunc,
) ChainSyncOptionFunc

WithRollBackwardFunc specifies the RollBackward callback function

func WithRollForwardFunc 

func WithRollForwardFunc(rollForwardFunc RollForwardFunc) ChainSyncOptionFunc

WithRollForwardFunc specifies the RollForward callback function. This will provided a parsed header or block

func WithRollForwardRawFunc added in v0.107.0 

func WithRollForwardRawFunc(
	rollForwardRawFunc RollForwardRawFunc,
) ChainSyncOptionFunc

WithRollForwardRawFunc specifies the RollForwardRaw callback function. This will provide the raw header or block

type Client 

type Client struct {
	*protocol.Protocol
	// contains filtered or unexported fields
}

Client implements the ChainSync client

func NewClient 

func NewClient(
	stateContext any,
	protoOptions protocol.ProtocolOptions,
	cfg *Config,
) *Client

NewClient returns a new ChainSync client object

func (*Client) GetAvailableBlockRange added in v0.38.0 

func (c *Client) GetAvailableBlockRange(
	intersectPoints []common.Point,
) (common.Point, common.Point, error)

GetAvailableBlockRange returns the start and end of the range of available blocks given the provided intersect point(s). Empty start/end points will be returned if there are no additional blocks available.

func (*Client) GetCurrentTip 

func (c *Client) GetCurrentTip() (*Tip, error)

GetCurrentTip returns the current chain tip

func (*Client) Start added in v0.73.3 

func (c *Client) Start()

func (*Client) Stop 

func (c *Client) Stop() error

Stop transitions the protocol to the Done state. No more protocol operations will be possible afterward

func (*Client) Sync 

func (c *Client) Sync(intersectPoints []common.Point) error

Sync begins a chain-sync operation using the provided intersect point(s). Incoming blocks will be delivered via the RollForward callback function specified in the protocol config

type Config 

type Config struct {
	RollBackwardFunc   RollBackwardFunc
	RollForwardFunc    RollForwardFunc
	RollForwardRawFunc RollForwardRawFunc
	FindIntersectFunc  FindIntersectFunc
	RequestNextFunc    RequestNextFunc
	IntersectTimeout   time.Duration
	BlockTimeout       time.Duration
	PipelineLimit      int
	RecvQueueSize      int
}

Config is used to configure the ChainSync protocol instance

func NewConfig 

func NewConfig(options ...ChainSyncOptionFunc) Config

NewConfig returns a new ChainSync config object with the provided options

type FindIntersectFunc added in v0.66.0 

type FindIntersectFunc func(CallbackContext, []common.Point) (common.Point, Tip, error)

type MsgAwaitReply 

type MsgAwaitReply struct {
	protocol.MessageBase
}

func NewMsgAwaitReply 

func NewMsgAwaitReply() *MsgAwaitReply

type MsgDone 

type MsgDone struct {
	protocol.MessageBase
}

func NewMsgDone 

func NewMsgDone() *MsgDone

type MsgFindIntersect 

type MsgFindIntersect struct {
	protocol.MessageBase
	Points []common.Point
}

func NewMsgFindIntersect 

func NewMsgFindIntersect(points []common.Point) *MsgFindIntersect

type MsgIntersectFound 

type MsgIntersectFound struct {
	protocol.MessageBase
	Point common.Point
	Tip   Tip
}

func NewMsgIntersectFound 

func NewMsgIntersectFound(point common.Point, tip Tip) *MsgIntersectFound

type MsgIntersectNotFound 

type MsgIntersectNotFound struct {
	protocol.MessageBase
	Tip Tip
}

func NewMsgIntersectNotFound 

func NewMsgIntersectNotFound(tip Tip) *MsgIntersectNotFound

type MsgRequestNext 

type MsgRequestNext struct {
	protocol.MessageBase
}

func NewMsgRequestNext 

func NewMsgRequestNext() *MsgRequestNext

type MsgRollBackward 

type MsgRollBackward struct {
	protocol.MessageBase
	Point common.Point
	Tip   Tip
}

func NewMsgRollBackward 

func NewMsgRollBackward(point common.Point, tip Tip) *MsgRollBackward

type MsgRollForwardNtC 

type MsgRollForwardNtC struct {
	protocol.MessageBase
	WrappedBlock cbor.Tag
	Tip          Tip
	// contains filtered or unexported fields
}

MsgRollForwardNtC is the NtC version of the RollForward message

func NewMsgRollForwardNtC 

func NewMsgRollForwardNtC(
	blockType uint,
	blockCbor []byte,
	tip Tip,
) *MsgRollForwardNtC

NewMsgRollForwardNtC returns a MsgRollForwardNtC with the provided parameters

func (*MsgRollForwardNtC) BlockCbor 

func (m *MsgRollForwardNtC) BlockCbor() []byte

BlockCbor returns the block CBOR

func (*MsgRollForwardNtC) BlockType 

func (m *MsgRollForwardNtC) BlockType() uint

BlockType returns the block type

func (*MsgRollForwardNtC) UnmarshalCBOR 

func (m *MsgRollForwardNtC) UnmarshalCBOR(data []byte) error

type MsgRollForwardNtN 

type MsgRollForwardNtN struct {
	protocol.MessageBase
	WrappedHeader WrappedHeader
	Tip           Tip
}

MsgRollForwardNtN is the NtN version of the RollForward message

func NewMsgRollForwardNtN 

func NewMsgRollForwardNtN(
	era uint,
	byronType uint,
	blockCbor []byte,
	tip Tip,
) (*MsgRollForwardNtN, error)

NewMsgRollForwardNtN returns a MsgRollForwardNtN with the provided parameters

type RequestNextFunc added in v0.66.0 

type RequestNextFunc func(CallbackContext) error

type RollBackwardFunc 

type RollBackwardFunc func(CallbackContext, common.Point, Tip) error

Callback function types

type RollForwardFunc 

type RollForwardFunc func(CallbackContext, uint, any, Tip) error

Callback function types

type RollForwardRawFunc added in v0.107.0 

type RollForwardRawFunc func(CallbackContext, uint, []byte, Tip) error

Callback function types

type Server 

type Server struct {
	*protocol.Protocol
	// contains filtered or unexported fields
}

Server implements the ChainSync server

func NewServer 

func NewServer(
	stateContext any,
	protoOptions protocol.ProtocolOptions,
	cfg *Config,
) *Server

NewServer returns a new ChainSync server object

func (*Server) AwaitReply added in v0.66.0 

func (s *Server) AwaitReply() error

func (*Server) RollBackward added in v0.66.0 

func (s *Server) RollBackward(point common.Point, tip Tip) error

func (*Server) RollForward added in v0.66.0 

func (s *Server) RollForward(blockType uint, blockData []byte, tip Tip) error

type StateContext added in v0.79.0 

type StateContext struct {
	// contains filtered or unexported fields
}

type Tip 

type Tip = common.Tip

Tip is an alias to keep historical code from breaking after moving this elsewhere

type WrappedBlock 

type WrappedBlock struct {
	BlockType uint
	BlockCbor cbor.RawMessage
	// contains filtered or unexported fields
}

WrappedBlock represents a block returned via a NtC RollForward message

func NewWrappedBlock 

func NewWrappedBlock(blockType uint, blockCbor []byte) *WrappedBlock

NewWrappedBlock returns a new WrappedBlock

type WrappedHeader 

type WrappedHeader struct {
	Era        uint
	RawMessage cbor.RawMessage
	// contains filtered or unexported fields
}

WrappedHeader represents a block header returned via NtN RollForward message

func NewWrappedHeader 

func NewWrappedHeader(
	era uint,
	byronType uint,
	blockCbor []byte,
) (*WrappedHeader, error)

NewWrappedHeader returns a new WrappedHeader

func (*WrappedHeader) ByronType 

func (w *WrappedHeader) ByronType() uint

ByronType returns the block type for Byron blocks

func (*WrappedHeader) HeaderCbor 

func (w *WrappedHeader) HeaderCbor() []byte

HeaderCbor returns the header CBOR

func (*WrappedHeader) MarshalCBOR 

func (w *WrappedHeader) MarshalCBOR() ([]byte, error)

func (*WrappedHeader) UnmarshalCBOR 

func (w *WrappedHeader) UnmarshalCBOR(data []byte) error

Source Files

View all Source files

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.