Documentation
¶
Overview ¶
Package chainsync implements the Ouroboros chain-sync protocol
Index ¶
- Constants
- Variables
- func NewMsgFromCbor(protoMode protocol.ProtocolMode, msgType uint, data []byte) (protocol.Message, error)
- func NewMsgFromCborNtC(msgType uint, data []byte) (protocol.Message, error)
- func NewMsgFromCborNtN(msgType uint, data []byte) (protocol.Message, error)
- type CallbackContext
- type ChainSync
- type ChainSyncOptionFunc
- func WithBlockTimeout(timeout time.Duration) ChainSyncOptionFunc
- func WithFindIntersectFunc(findIntersectFunc FindIntersectFunc) ChainSyncOptionFunc
- func WithIntersectTimeout(timeout time.Duration) ChainSyncOptionFunc
- func WithPipelineLimit(limit int) ChainSyncOptionFunc
- func WithRecvQueueSize(size int) ChainSyncOptionFunc
- func WithRequestNextFunc(requestNextFunc RequestNextFunc) ChainSyncOptionFunc
- func WithRollBackwardFunc(rollBackwardFunc RollBackwardFunc) ChainSyncOptionFunc
- func WithRollForwardFunc(rollForwardFunc RollForwardFunc) ChainSyncOptionFunc
- func WithRollForwardRawFunc(rollForwardRawFunc RollForwardRawFunc) ChainSyncOptionFunc
- type Client
- type Config
- type FindIntersectFunc
- type MsgAwaitReply
- type MsgDone
- type MsgFindIntersect
- type MsgIntersectFound
- type MsgIntersectNotFound
- type MsgRequestNext
- type MsgRollBackward
- type MsgRollForwardNtC
- type MsgRollForwardNtN
- type RequestNextFunc
- type RollBackwardFunc
- type RollForwardFunc
- type RollForwardRawFunc
- type Server
- type StateContext
- type Tip
- type WrappedBlock
- type WrappedHeader
Constants ¶
const ( ProtocolName = "chain-sync" ProtocolIdNtN uint16 = 2 ProtocolIdNtC uint16 = 5 )
Protocol identifiers
const ( MaxPipelineLimit = 100 // Max pipelined requests MaxRecvQueueSize = 100 // Max receive queue size (messages) DefaultPipelineLimit = 50 // Default pipeline limit DefaultRecvQueueSize = 50 // Default queue size MaxPendingMessageBytes = 102400 // Max pending message bytes (100KB) )
Protocol limits per Ouroboros Network Specification
const ( IdleTimeout = 60 * time.Second // Timeout for client to send next request CanAwaitTimeout = 300 * time.Second // Timeout for server to provide next block or await IntersectTimeout = 5 * time.Second // Timeout for server to respond to intersect request MustReplyTimeout = 300 * time.Second // Timeout for server to provide next block )
Protocol state timeout constants per network specification
const ( MessageTypeRequestNext = 0 MessageTypeAwaitReply = 1 MessageTypeRollForward = 2 MessageTypeRollBackward = 3 MessageTypeFindIntersect = 4 MessageTypeIntersectFound = 5 MessageTypeIntersectNotFound = 6 MessageTypeDone = 7 )
Message types
Variables ¶
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 }
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 }
var ErrIntersectNotFound = errors.New("chain intersection not found")
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
var IncrementPipelineCount = func(context any, msg protocol.Message) bool { s := context.(*StateContext) s.mu.Lock() defer s.mu.Unlock() s.pipelineCount++ return true }
var PipelineIsEmtpy = func(context any, msg protocol.Message) bool { s := context.(*StateContext) s.mu.Lock() defer s.mu.Unlock() return s.pipelineCount == 0 }
var PipelineIsNotEmpty = func(context any, msg protocol.Message) bool { s := context.(*StateContext) s.mu.Lock() defer s.mu.Unlock() return s.pipelineCount > 0 }
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 ¶
NewMsgFromCborNtC 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 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
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 ¶
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 ¶
GetCurrentTip returns the current chain tip
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 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, error)
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 ¶
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 (*Server) RollBackward ¶ added in v0.66.0
type StateContext ¶ added in v0.79.0
type StateContext struct {
// contains filtered or unexported fields
}
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