chainmanager

Documentation

Overview

This package implements a protocol for running a chain in a node. Its main responsibilities:

• Track, which branch is the latest/correct one.
• Maintain a set of committee logs (1 for each committee this node participates in).
• Maintain a set of consensus instances (one of them is the current one).
• Supervise the Mempool and StateMgr.
• Handle messages from the NodeConn (AO confirmed / rejected, Request received).
• Posting StateTX to NodeConn.

> VARIABLES: > LatestActiveCmt -- The latest committee, that was active. > This field will be nil if the node is not part of the committee. > On the resynchronization it will store the previous active committee. > LatestActiveAO -- The latest AO we are building upon. > Derived, equal to NeedConsensus.BaseAO. > LatestConfirmedAO -- The latest ConfirmedAO from L1. > This one usually follows the LatestAliasOutput, > but can be published from outside and override the LatestAliasOutput. > AccessNodes -- The set of access nodes for the current head. > Union of On-Chain access nodes and the nodes permitted by this node. > NeedConsensus -- A request to run consensus. > Always set based on output of the main CmtLog. > NeedPublishTX -- Requests to publish TX'es. > - Added upon reception of the Consensus Output, > if it is still in NeedConsensus at the time. > - Removed on PublishResult from the NodeConn. > > UPON Reception of ConfirmedAO: > Set LatestConfirmedAO <- ConfirmedAO > IF this node is in the committee THEN > Pass it to the corresponding CmtLog; HandleCmtLogOutput. > ELSE > IF LatestActiveCmt != nil THEN > Send Suspend to Last Active CmtLog; HandleCmtLogOutput > Set LatestActiveCmt <- NIL > Set NeedConsensus <- NIL > UPON Reception of PublishResult: > Clear the TX from the NeedPublishTX variable. > If result.confirmed = false THEN > Forward it to ChainMgr; HandleCmtLogOutput. > ELSE > NOP // AO has to be received as ConfirmedAO. > UPON Reception of Consensus Output/DONE: > IF ConsensusOutput.BaseAO == NeedConsensus THEN > Add ConsensusOutput.TX to NeedPublishTX > Forward the message to the corresponding CmtLog; HandleCmtLogOutput. > Update AccessNodes. > UPON Reception of Consensus Output/SKIP: > Forward the message to the corresponding CmtLog; HandleCmtLogOutput. > UPON Reception of Consensus Timeout: > Forward the message to the corresponding CmtLog; HandleCmtLogOutput. > UPON Reception of CmtLog.NextLI message: > Forward it to the corresponding CmtLog; HandleCmtLogOutput. > > PROCEDURE HandleCmtLogOutput(cmt): > Wrap out messages. > IF cmt == LatestActiveCmt || LatestActiveCmt == NIL THEN > Set LatestActiveCmt <- cmt > Set NeedConsensus <- output.NeedConsensus // Can be nil > ELSE > IF output.NeedConsensus == nil THEN > RETURN // No need to change the committee. > IF LatestActiveCmt != nil THEN > Suspend(LatestActiveCmt) > Set LatestActiveCmt <- cmt > Set NeedConsensus <- output.NeedConsensus

TODO: Why AM is not notified on the committee nodes after rotation?

Index

• Variables
• func NewInputAliasOutputConfirmed(aliasOutput *isc.AliasOutputWithID) gpa.Input
• func NewInputCanPropose() gpa.Input
• func NewInputChainTxPublishResult(committeeAddr iotago.Ed25519Address, logIndex cmt_log.LogIndex, ...) gpa.Input
• func NewInputConsensusOutputDone(committeeAddr iotago.Ed25519Address, logIndex cmt_log.LogIndex, ...) gpa.Input
• func NewInputConsensusOutputSkip(committeeAddr iotago.Ed25519Address, logIndex cmt_log.LogIndex, ...) gpa.Input
• func NewInputConsensusTimeout(committeeAddr iotago.Ed25519Address, logIndex cmt_log.LogIndex) gpa.Input
• func NewInputMilestoneReceived() gpa.Input
• func NewMsgBlockProduced(recipient gpa.NodeID, tx *iotago.Transaction, block state.Block) gpa.Message
• func NewMsgCmtLog(committeeAddr iotago.Ed25519Address, wrapped gpa.Message) gpa.Message
• type ChainMgr
  • func New(me gpa.NodeID, chainID isc.ChainID, chainStore state.Store, ...) (ChainMgr, error)
• type NeedConsensus
  • func (nc *NeedConsensus) IsFor(output *cmt_log.Output) bool
  • func (nc *NeedConsensus) String() string
• type NeedPublishTX
• type Output
  • func (o *Output) LatestActiveAliasOutput() *isc.AliasOutputWithID
  • func (o *Output) LatestConfirmedAliasOutput() *isc.AliasOutputWithID
  • func (o *Output) NeedConsensus() *NeedConsensus
  • func (o *Output) NeedPublishTX() *shrinkingmap.ShrinkingMap[iotago.TransactionID, *NeedPublishTX]
  • func (o *Output) String() string
• type VarAccessNodeState
  • func NewVarAccessNodeState(chainID isc.ChainID, log *logger.Logger) VarAccessNodeState

Variables

var ErrNotInCommittee = errors.New("ErrNotInCommittee")

Functions

func NewInputAliasOutputConfirmed

func NewInputAliasOutputConfirmed(aliasOutput *isc.AliasOutputWithID) gpa.Input

func NewInputCanPropose

func NewInputCanPropose() gpa.Input

func NewInputChainTxPublishResult

func NewInputChainTxPublishResult(committeeAddr iotago.Ed25519Address, logIndex cmt_log.LogIndex, txID iotago.TransactionID, aliasOutput *isc.AliasOutputWithID, confirmed bool) gpa.Input

func NewInputConsensusOutputDone

func NewInputConsensusOutputDone(
	committeeAddr iotago.Ed25519Address,
	logIndex cmt_log.LogIndex,
	proposedBaseAO iotago.OutputID,
	consensusResult *cons.Result,
) gpa.Input

func NewInputConsensusOutputSkip

func NewInputConsensusOutputSkip(
	committeeAddr iotago.Ed25519Address,
	logIndex cmt_log.LogIndex,
	proposedBaseAO iotago.OutputID,
) gpa.Input

func NewInputConsensusTimeout

func NewInputConsensusTimeout(committeeAddr iotago.Ed25519Address, logIndex cmt_log.LogIndex) gpa.Input

func NewInputMilestoneReceived

func NewInputMilestoneReceived() gpa.Input

func NewMsgBlockProduced

func NewMsgBlockProduced(recipient gpa.NodeID, tx *iotago.Transaction, block state.Block) gpa.Message

func NewMsgCmtLog

func NewMsgCmtLog(committeeAddr iotago.Ed25519Address, wrapped gpa.Message) gpa.Message

Types

type ChainMgr

type ChainMgr interface {
	AsGPA() gpa.GPA
}

func New

func New(
	me gpa.NodeID,
	chainID isc.ChainID,
	chainStore state.Store,
	consensusStateRegistry cmt_log.ConsensusStateRegistry,
	dkShareRegistryProvider registry.DKShareRegistryProvider,
	nodeIDFromPubKey func(pubKey *cryptolib.PublicKey) gpa.NodeID,
	activeNodesCB func() ([]*cryptolib.PublicKey, []*cryptolib.PublicKey),
	trackActiveStateCB func(ao *isc.AliasOutputWithID),
	savePreliminaryBlockCB func(block state.Block),
	committeeUpdatedCB func(dkShare tcrypto.DKShare),
	deriveAOByQuorum bool,
	pipeliningLimit int,
	postponeRecoveryMilestones int,
	metrics *metrics.ChainCmtLogMetrics,
	log *logger.Logger,
) (ChainMgr, error)

type NeedConsensus

type NeedConsensus struct {
	CommitteeAddr   iotago.Ed25519Address
	LogIndex        cmt_log.LogIndex
	DKShare         tcrypto.DKShare
	BaseAliasOutput *isc.AliasOutputWithID
}

func (*NeedConsensus) IsFor

func (nc *NeedConsensus) IsFor(output *cmt_log.Output) bool

func (*NeedConsensus) String

func (nc *NeedConsensus) String() string

type NeedPublishTX

type NeedPublishTX struct {
	CommitteeAddr     iotago.Ed25519Address
	LogIndex          cmt_log.LogIndex
	TxID              iotago.TransactionID
	Tx                *iotago.Transaction
	BaseAliasOutputID iotago.OutputID        // The consumed AliasOutput.
	NextAliasOutput   *isc.AliasOutputWithID // The next one (produced by the TX.)
}

type Output

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

func (*Output) LatestActiveAliasOutput

func (o *Output) LatestActiveAliasOutput() *isc.AliasOutputWithID

func (*Output) LatestConfirmedAliasOutput

func (o *Output) LatestConfirmedAliasOutput() *isc.AliasOutputWithID

func (*Output) NeedConsensus

func (o *Output) NeedConsensus() *NeedConsensus

func (*Output) NeedPublishTX

func (o *Output) NeedPublishTX() *shrinkingmap.ShrinkingMap[iotago.TransactionID, *NeedPublishTX]

func (*Output) String

func (o *Output) String() string

type VarAccessNodeState

type VarAccessNodeState interface {
	Tip() *isc.AliasOutputWithID
	// Considers the produced (not yet confirmed) block / TX and returns new tip AO.
	// The returned bool indicates if the tip has changed because of this call.
	// This function should return L1 commitment, if the corresponding block should be added to the store.
	BlockProduced(tx *iotago.Transaction) (*isc.AliasOutputWithID, bool, *state.L1Commitment)
	// Considers a confirmed AO and returns new tip AO.
	// The returned bool indicates if the tip has changed because of this call.
	BlockConfirmed(ao *isc.AliasOutputWithID) (*isc.AliasOutputWithID, bool)
}

Tracks the active state at the access nodes. If this node is part of the committee, then the tip tracked by this node should be ignored and the state tracked by the committee should be used. The algorithm itself is similar to the `varLocalView` in the `cmtLog`.

func NewVarAccessNodeState

func NewVarAccessNodeState(chainID isc.ChainID, log *logger.Logger) VarAccessNodeState