chain

Documentation

Overview

This runs single chain will all the committees, mempool, state mgr etc. The main task for this package to run the protocol as in a threaded environment, communicate between ChainMgr, Mempool, StateMgr, NodeConn and ConsensusInstances.

The following threads (goroutines) are running for a chain:

• ChainMgr (the main synchronizing thread)
• Mempool
• StateMgr
• Consensus (a thread for each instance).

This object interacts with:

• NodeConn.
• Administrative functions.

Index

• type AliasOutputHandler
• type AwaitReceipt
  • func NewAwaitReceipt(cleanupEvery int, log *logger.Logger) AwaitReceipt
• type Chain
  • func New(ctx context.Context, log *logger.Logger, chainID isc.ChainID, ...) (Chain, error)
• type ChainCore
• type ChainListener
  • func NewEmptyChainListener() ChainListener
• type ChainNodeConn
• type ChainRequests
• type CommitteeInfo
• type ConsensusPipeMetrics
• type ConsensusWorkflowStatus
• type MilestoneHandler
• type NodeConnection
• type PeerStatus
• type RequestOutputHandler
• type StateFreshness
  • func (sf StateFreshness) String() string
• type StateTracker
  • func NewStateTracker(ctx context.Context, stateMgr statemanager.StateMgr, ...) StateTracker
• type StateTrackerStepCB
• type TxPostHandler

Types

type AliasOutputHandler

type AliasOutputHandler = func(outputInfo *isc.OutputInfo)

The Alias Outputs must be passed here in-order. The last alias output in the list is the unspent one (if there is a chain of outputs confirmed in a milestone).

type AwaitReceipt

type AwaitReceipt interface {
	Await(query *awaitReceiptReq)
	ConsiderState(state state.State, blocksAdded []state.Block) // Respond to all queries, that have receipts in the state.
	StatusString() string
}

AwaitReceipt implements await for request receipts.

func NewAwaitReceipt

func NewAwaitReceipt(cleanupEvery int, log *logger.Logger) AwaitReceipt

type Chain

type Chain interface {
	ChainCore
	ChainRequests
	// This is invoked when a node owner updates the chain configuration,
	// possibly to update the per-node accessNode list.
	ConfigUpdated(accessNodesPerNode []*cryptolib.PublicKey)
	// This is invoked when the accessMgr determines the nodes which
	// consider this node as an access node for this chain. The chain
	// can query the nodes for blocks, etc. NOTE: servers = access⁻¹
	ServersUpdated(serverNodes []*cryptolib.PublicKey)
	// Metrics and the current descriptive state.
	GetChainMetrics() metrics.IChainMetrics
	GetConsensusPipeMetrics() ConsensusPipeMetrics // TODO: Review this.
	GetConsensusWorkflowStatus() ConsensusWorkflowStatus
}

func New

func New(
	ctx context.Context,
	log *logger.Logger,
	chainID isc.ChainID,
	chainStore indexedstore.IndexedStore,
	nodeConn NodeConnection,
	nodeIdentity *cryptolib.KeyPair,
	processorConfig *processors.Config,
	dkShareRegistryProvider registry.DKShareRegistryProvider,
	consensusStateRegistry cmt_log.ConsensusStateRegistry,
	blockWAL sm_gpa_utils.BlockWAL,
	listener ChainListener,
	accessNodesFromNode []*cryptolib.PublicKey,
	net peering.NetworkProvider,
	chainMetrics metrics.IChainMetrics,
	shutdownCoordinator *shutdown.Coordinator,
	onChainConnect func(),
	onChainDisconnect func(),
	deriveAliasOutputByQuorum bool,
	pipeliningLimit int,
	consensusDelay time.Duration,
) (Chain, error)

type ChainCore

type ChainCore interface {
	ID() isc.ChainID
	// Returns the current latest confirmed alias output and the active one.
	// The active AO can be ahead of the confirmed one by several blocks.
	// Both values can be nil, if the node haven't received an output from
	// L1 yet (after a restart or a chain activation).
	LatestAliasOutput(freshness StateFreshness) (*isc.AliasOutputWithID, error)
	LatestState(freshness StateFreshness) (state.State, error)
	GetCommitteeInfo() *CommitteeInfo // TODO: Review, maybe we can reorganize the CommitteeInfo structure.
	Store() indexedstore.IndexedStore // Use LatestState whenever possible. That will work faster.
	Processors() *processors.Cache
	GetChainNodes() []peering.PeerStatusProvider     // CommitteeNodes + AccessNodes
	GetCandidateNodes() []*governance.AccessNodeInfo // All the current candidates.
	Log() *logger.Logger
}

type ChainListener

type ChainListener interface {
	mempool.ChainListener
	AccessNodesUpdated(chainID isc.ChainID, accessNodes []*cryptolib.PublicKey)
	ServerNodesUpdated(chainID isc.ChainID, serverNodes []*cryptolib.PublicKey)
}

Implementation of this interface will receive events in the chain. Initial intention was to provide info to the published/WebSocket endpoint. All the function MUST NOT BLOCK.

func NewEmptyChainListener

func NewEmptyChainListener() ChainListener

type ChainNodeConn

type ChainNodeConn interface {
	// Publishing can be canceled via the context.
	// The result must be returned via the callback, unless ctx is canceled first.
	// PublishTX handles promoting and reattachments until the tx is confirmed or the context is canceled.
	PublishTX(
		ctx context.Context,
		chainID isc.ChainID,
		tx *iotago.Transaction,
		callback TxPostHandler,
	) error
	// Alias outputs are expected to be returned in order. Considering the Hornet node, the rules are:
	//   - Upon Attach -- existing unspent alias output is returned FIRST.
	//   - Upon receiving a spent/unspent AO from L1 they are returned in
	//     the same order, as the milestones are issued.
	//   - If a single milestone has several alias outputs, they have to be ordered
	//     according to the chain of TXes.
	//
	// NOTE: Any out-of-order AO will be considered as a rollback or AO by the chain impl.
	AttachChain(
		ctx context.Context,
		chainID isc.ChainID,
		recvRequestCB RequestOutputHandler,
		recvAliasOutput AliasOutputHandler,
		recvMilestone MilestoneHandler,
		onChainConnect func(),
		onChainDisconnect func(),
	)
}

type ChainRequests

type ChainRequests interface {
	ReceiveOffLedgerRequest(request isc.OffLedgerRequest, sender *cryptolib.PublicKey)
	AwaitRequestProcessed(ctx context.Context, requestID isc.RequestID, confirmed bool) <-chan *blocklog.RequestReceipt
}

type CommitteeInfo

type CommitteeInfo struct {
	Address       iotago.Address
	Size          uint16
	Quorum        uint16
	QuorumIsAlive bool
	PeerStatus    []*PeerStatus
}

type ConsensusPipeMetrics

type ConsensusPipeMetrics interface {
	GetEventStateTransitionMsgPipeSize() int
	GetEventPeerLogIndexMsgPipeSize() int
	GetEventACSMsgPipeSize() int
	GetEventVMResultMsgPipeSize() int
	GetEventTimerMsgPipeSize() int
}

type ConsensusWorkflowStatus

type ConsensusWorkflowStatus interface {
	IsStateReceived() bool
	IsBatchProposalSent() bool
	IsConsensusBatchKnown() bool
	IsVMStarted() bool
	IsVMResultSigned() bool
	IsTransactionFinalized() bool
	IsTransactionPosted() bool
	IsTransactionSeen() bool
	IsInProgress() bool
	GetBatchProposalSentTime() time.Time
	GetConsensusBatchKnownTime() time.Time
	GetVMStartedTime() time.Time
	GetVMResultSignedTime() time.Time
	GetTransactionFinalizedTime() time.Time
	GetTransactionPostedTime() time.Time
	GetTransactionSeenTime() time.Time
	GetCompletedTime() time.Time
	GetCurrentStateIndex() uint32
}

type MilestoneHandler

type MilestoneHandler = func(timestamp time.Time)

type NodeConnection

type NodeConnection interface {
	ChainNodeConn
	Run(ctx context.Context) error
	WaitUntilInitiallySynced(context.Context) error
	GetBech32HRP() iotago.NetworkPrefix
	GetL1Params() *parameters.L1Params
	GetL1ProtocolParams() *iotago.ProtocolParameters
}

type PeerStatus

type PeerStatus struct {
	Name       string
	Index      uint16
	PubKey     *cryptolib.PublicKey
	PeeringURL string
	Connected  bool
}

type RequestOutputHandler

type RequestOutputHandler = func(outputInfo *isc.OutputInfo)

type StateFreshness

type StateFreshness byte

const (
	ActiveOrCommittedState StateFreshness = iota // ActiveState, if exist; Confirmed state otherwise.
	ActiveState                                  // The state the chain build next TX on, can be ahead of ConfirmedState.
	ConfirmedState                               // The state confirmed on L1.
)

func (StateFreshness) String

func (sf StateFreshness) String() string

type StateTracker

type StateTracker interface {
	//
	// The main functions provided by this component.
	TrackAliasOutput(ao *isc.AliasOutputWithID, strict bool)
	AwaitRequestReceipt(query *awaitReceiptReq)
	//
	// The following 2 functions are only to move the channel receive loop to the main ChainNode thread.
	ChainNodeAwaitStateMgrCh() <-chan *sm_inputs.ChainFetchStateDiffResults
	ChainNodeStateMgrResponse(*sm_inputs.ChainFetchStateDiffResults)
}

Tracks a single chain of state transitions. We will have 2 instances of it:

• one for tracking the active state. It is needed for mempool to clear the requests.
• one for the committed state to await for committed request receipts.

func NewStateTracker

func NewStateTracker(
	ctx context.Context,
	stateMgr statemanager.StateMgr,
	haveLatestCB StateTrackerStepCB,
	metricWantStateIndexCB func(uint32),
	metricHaveStateIndexCB func(uint32),
	log *logger.Logger,
) StateTracker

type StateTrackerStepCB

type StateTrackerStepCB = func(st state.State, from, till *isc.AliasOutputWithID, added, removed []state.Block)

type TxPostHandler

type TxPostHandler = func(tx *iotago.Transaction, confirmed bool)