chainsync

package
v0.22.0 Latest Latest
Warning

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

 Go to latest Published: Mar 7, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ClientAddedEventType is emitted when a new chainsync
	// client is registered.
	ClientAddedEventType event.EventType = "chainsync.client_added"

	// ClientRemovedEventType is emitted when a chainsync client
	// is unregistered (e.g. on disconnect).
	ClientRemovedEventType event.EventType = "chainsync.client_removed"

	// ClientSyncedEventType is emitted when a chainsync client
	// reaches the upstream chain tip.
	ClientSyncedEventType event.EventType = "chainsync.client_synced"

	// ClientStalledEventType is emitted when a chainsync client
	// has not received any headers within the stall timeout.
	ClientStalledEventType event.EventType = "chainsync.client_stalled"

	// ForkDetectedEventType is emitted when two clients report
	// different block hashes for the same slot.
	ForkDetectedEventType event.EventType = "chainsync.fork_detected"

	// ClientRemoveRequestedEventType is emitted when another
	// component requests chainsync to remove a tracked client.
	ClientRemoveRequestedEventType event.EventType = "chainsync.client_remove_requested"
)
View Source 
const DefaultMaxClients = 3

DefaultMaxClients is the default maximum number of concurrent chainsync clients.

View Source 
const DefaultStallTimeout = 2 * time.Minute

DefaultStallTimeout is the default duration after which a client with no activity is considered stalled. This value must stay in sync with config.DefaultChainsyncConfig() and the fallback in internal/node/node.go.

Variables

This section is empty.

Functions

This section is empty.

Types

type ChainsyncClientState 

type ChainsyncClientState struct {
	ChainIter            *chain.ChainIterator
	Cursor               ocommon.Point
	NeedsInitialRollback bool
}

ChainsyncClientState holds per-connection state for a chainsync server-side client (node-to-client connections).

type ClientAddedEvent added in v0.22.0 

type ClientAddedEvent struct {
	ConnId       ouroboros.ConnectionId
	TotalClients int
}

ClientAddedEvent contains details about a newly registered chainsync client.

type ClientRemoveRequestedEvent added in v0.22.0 

type ClientRemoveRequestedEvent struct {
	ConnId  ouroboros.ConnectionId
	ConnKey string
	Reason  string
}

ClientRemoveRequestedEvent contains the connection details for a requested tracked-client removal.

type ClientRemovedEvent added in v0.22.0 

type ClientRemovedEvent struct {
	ConnId       ouroboros.ConnectionId
	TotalClients int
	WasPrimary   bool
}

ClientRemovedEvent contains details about a removed chainsync client.

type ClientStalledEvent added in v0.22.0 

type ClientStalledEvent struct {
	ConnId ouroboros.ConnectionId
	Slot   uint64
}

ClientStalledEvent is published when a client exceeds the stall timeout.

type ClientStatus added in v0.22.0 

type ClientStatus int

ClientStatus represents the sync status of a chainsync client. 

const (
	// ClientStatusSyncing indicates the client is actively
	// receiving headers.
	ClientStatusSyncing ClientStatus = iota
	// ClientStatusSynced indicates the client has reached the
	// upstream chain tip.
	ClientStatusSynced
	// ClientStatusStalled indicates the client has not received
	// activity within the stall timeout.
	ClientStatusStalled
	// ClientStatusFailed indicates the client encountered an
	// error.
	ClientStatusFailed
)

func (ClientStatus) String added in v0.22.0 

func (s ClientStatus) String() string

String returns a human-readable name for the ClientStatus.

type ClientSyncedEvent added in v0.22.0 

type ClientSyncedEvent struct {
	ConnId ouroboros.ConnectionId
	Slot   uint64
}

ClientSyncedEvent is published when a client reaches the upstream chain tip.

type Config added in v0.22.0 

type Config struct {
	MaxClients   int
	StallTimeout time.Duration
}

Config holds configuration for the chainsync State.

func DefaultConfig added in v0.22.0 

func DefaultConfig() Config

DefaultConfig returns the default chainsync configuration.

type ForkDetectedEvent added in v0.22.0 

type ForkDetectedEvent struct {
	Slot    uint64
	HashA   []byte
	HashB   []byte
	ConnIdA ouroboros.ConnectionId
	ConnIdB ouroboros.ConnectionId
	Point   ocommon.Point
}

ForkDetectedEvent is published when two clients report different block hashes at the same slot.

type State 

type State struct {
	sync.Mutex
	// contains filtered or unexported fields
}

State manages chainsync client connections and header tracking for both server-side (N2C) and outbound (N2N) connections.

func NewState 

func NewState(
	eventBus *event.EventBus,
	ledgerState *ledger.LedgerState,
) *State

NewState creates a new chainsync State with the given event bus and ledger state using default configuration.

func NewStateWithConfig added in v0.22.0 

func NewStateWithConfig(
	eventBus *event.EventBus,
	ledgerState *ledger.LedgerState,
	cfg Config,
) *State

NewStateWithConfig creates a new chainsync State with the given event bus, ledger state, and configuration.

func (*State) AddClient 

func (s *State) AddClient(
	connId connection.ConnectionId,
	intersectPoint ocommon.Point,
) (*ChainsyncClientState, error)

AddClient registers a server-side (N2C) chainsync client.

func (*State) AddClientConnId added in v0.21.0 

func (s *State) AddClientConnId(
	connId ouroboros.ConnectionId,
) bool

AddClientConnId adds a connection ID to the set of tracked chainsync clients, enforcing the configured MaxClients limit. Returns true if the client was added, false if rejected (already tracked or at capacity). If no active client exists, this connection is automatically set as the active client.

func (*State) CheckStalledClients added in v0.22.0 

func (s *State) CheckStalledClients() []ouroboros.ConnectionId

CheckStalledClients scans all tracked clients and marks any that have exceeded the stall timeout. If the primary client is stalled, a failover to the next best client is triggered. Returns the list of connection IDs that were newly marked as stalled.

func (*State) ClearSeenHeaders added in v0.22.0 

func (s *State) ClearSeenHeaders()

ClearSeenHeaders removes all entries from the header deduplication cache. This should be called on rollback to avoid stale entries.

func (*State) ClientConnCount added in v0.21.0 

func (s *State) ClientConnCount() int

ClientConnCount returns the number of tracked chainsync clients.

func (*State) GetClientConnId 

func (s *State) GetClientConnId() *ouroboros.ConnectionId

GetClientConnId returns the active chainsync client connection ID. This is the connection that should be used for block fetching.

func (*State) GetClientConnIds added in v0.21.0 

func (s *State) GetClientConnIds() []ouroboros.ConnectionId

GetClientConnIds returns all tracked chainsync client connection IDs.

func (*State) GetTrackedClient added in v0.22.0 

func (s *State) GetTrackedClient(
	connId ouroboros.ConnectionId,
) *TrackedClient

GetTrackedClient returns a deep copy of the TrackedClient for the given connection ID, or nil if not found. Byte slices inside Point.Hash are cloned so the caller cannot race with concurrent UpdateClientTip calls.

func (*State) GetTrackedClients added in v0.22.0 

func (s *State) GetTrackedClients() []TrackedClient

GetTrackedClients returns deep copies of all tracked clients.

func (*State) HandleClientRemoveRequestedEvent added in v0.22.0 

func (s *State) HandleClientRemoveRequestedEvent(evt event.Event)

HandleClientRemoveRequestedEvent removes a tracked client when a component publishes a client removal request event.

func (*State) HasClientConnId added in v0.21.0 

func (s *State) HasClientConnId(
	connId ouroboros.ConnectionId,
) bool

HasClientConnId returns true if the connection ID is being tracked.

func (*State) MarkClientSynced added in v0.22.0 

func (s *State) MarkClientSynced(
	connId ouroboros.ConnectionId,
)

MarkClientSynced marks a tracked client as synced (at chain tip).

func (*State) MaxClients added in v0.22.0 

func (s *State) MaxClients() int

MaxClients returns the configured maximum number of chainsync clients.

func (*State) PruneSeenHeaders added in v0.22.0 

func (s *State) PruneSeenHeaders(beforeSlot uint64)

PruneSeenHeaders removes entries from the header deduplication cache for slots older than the given slot.

func (*State) RemoveClient 

func (s *State) RemoveClient(connId connection.ConnectionId)

RemoveClient unregisters a server-side (N2C) chainsync client.

func (*State) RemoveClientConnId 

func (s *State) RemoveClientConnId(
	connId ouroboros.ConnectionId,
)

RemoveClientConnId removes a connection from tracking. If this was the active client, promotes the client with the highest tip slot as the new primary.

func (*State) SetClientConnId 

func (s *State) SetClientConnId(connId ouroboros.ConnectionId)

SetClientConnId sets the active chainsync client connection ID. This is used when chain selection determines a new best peer.

func (*State) TryAddClientConnId added in v0.21.0 

func (s *State) TryAddClientConnId(
	connId ouroboros.ConnectionId,
	maxClients int,
) bool

TryAddClientConnId atomically checks if a connection can be added (not already tracked and under maxClients limit) and adds it if allowed. Returns true if the connection was added, false otherwise.

func (*State) UpdateClientTip added in v0.22.0 

func (s *State) UpdateClientTip(
	connId ouroboros.ConnectionId,
	point ocommon.Point,
	tip ochainsync.Tip,
) bool

UpdateClientTip updates the cursor, tip, and activity tracking for a tracked client. Returns true if the header at this point is new (not a duplicate).

type TrackedClient added in v0.22.0 

type TrackedClient struct {
	ConnId       ouroboros.ConnectionId
	Cursor       ocommon.Point
	Tip          ochainsync.Tip
	Status       ClientStatus
	LastActivity time.Time
	HeadersRecv  uint64
	// TODO: BytesRecv needs to be wired to the underlying
	// connection's byte counter. Currently unused.
	BytesRecv uint64
}

TrackedClient holds per-connection state for a tracked chainsync client (outbound node-to-node connections).

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.