cmtLog

Documentation

Overview

package cmtLog is responsible for producing a log of chain's block decisions for a particular committee. The main tasks for this module are:

• Track the head of the chain log for a committee.
• Track which blocks are approved, pending or reverted.
• Handle startup and recovery scenarios.

The algorithm at a high level:

> ON Startup: > Let prevLI <- TRY restoring the last started LogIndex ELSE 0 > MinLI <- prevLI + 1 > LogIndex.Start(prevLI) > TryProposeConsensus() > UPON AliasOutput (AO) {Confirmed | Rejected} by L1: > LocalView.Update(AO) > IF LocalView changed THEN > LogIndex.L1ReplacedBaseAliasOutput() > TryProposeConsensus() > ON ConsensusOutput/DONE (CD) > LocalView.Update(CD) > IF LocalView changed THEN > LogIndex.ConsensusOutput(CD.LogIndex) > TryProposeConsensus() > ON ConsensusOutput/SKIP (CS) > LogIndex.ConsensusOutput(CS.LogIndex) > TryProposeConsensus() > ON ConsensusTimeout (CT) > LogIndex.ConsensusTimeout(CT.LogIndex) > TryProposeConsensus() > ON Suspend: > Suspended <- TRUE > TryProposeConsensus() > ON Reception of ⟨NextLI, •⟩ message: > LogIndex.Receive(⟨NextLI, •⟩ message). > TryProposeConsensus() > PROCEDURE TryProposeConsensus: > IF ∧ LocalView.BaseAO ≠ NIL > ∧ LogIndex > ConsensusLI > ∧ LogIndex ≥ MinLI // ⇒ LogIndex ≠ NIL > ∧ ¬ Suspended > THEN > Persist LogIndex > ConsensusLI <- LogIndex > Propose LocalView.BaseAO for LogIndex > ELSE > Don't propose any consensus.

See `WaspChainRecovery.tla` for more precise specification.

Notes and invariants:

• Here only a single consensus instance will be considered needed for this node at a time. Other instances may continue running, but their results will be ignored. That's because a consensus takes an input from the previous consensus output (the base alias ID and other parts that depend on it).
• A consensus is started when we have new log index greater than that we have crashed with, and there is an alias output received.

## Summary.

Inputs expected:

• Consensus: Start -> Done | Timeout.
• AliasOutput: Confirmed | Rejected -> {}.
• Suspend.

Messages exchanged:

• NextLogIndex (private, between cmtLog instances).

Index

• Variables
• func NewInputAliasOutputConfirmed(aliasOutput *isc.AliasOutputWithID) gpa.Input
• func NewInputAliasOutputRejected(aliasOutput *isc.AliasOutputWithID) gpa.Input
• func NewInputConsensusOutputDone(logIndex LogIndex, baseAliasOutputID iotago.OutputID, ...) gpa.Input
• func NewInputConsensusOutputSkip(logIndex LogIndex, baseAliasOutputID iotago.OutputID) gpa.Input
• func NewInputConsensusTimeout(logIndex LogIndex) gpa.Input
• func NewInputStart() gpa.Input
• func NewInputSuspend() gpa.Input
• func UnmarshalMessage(data []byte) (gpa.Message, error)
• type CmtLog
  • func New(me gpa.NodeID, chainID isc.ChainID, dkShare tcrypto.DKShare, ...) (CmtLog, error)
• type ConsensusStateRegistry
• type LogIndex
  • func NilLogIndex() LogIndex
  • func (li LogIndex) AsUint32() uint32
  • func (li LogIndex) Bytes() []byte
  • func (li LogIndex) IsNil() bool
  • func (li LogIndex) Next() LogIndex
• type Output
  • func (o *Output) GetBaseAliasOutput() *isc.AliasOutputWithID
  • func (o *Output) GetLogIndex() LogIndex
  • func (o *Output) String() string
• type State
• type VarLocalView
  • func NewVarLocalView() VarLocalView
• type VarLogIndex
  • func NewVarLogIndex(nodeIDs []gpa.NodeID, n int, f int, initLI LogIndex, log *logger.Logger) VarLogIndex

Variables

var ErrCmtLogStateNotFound = errors.New("errCmtLogStateNotFound")

Functions

func NewInputAliasOutputConfirmed

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

func NewInputAliasOutputRejected

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

func NewInputConsensusOutputDone

func NewInputConsensusOutputDone(
	logIndex LogIndex,
	baseAliasOutputID iotago.OutputID,
	nextAliasOutput *isc.AliasOutputWithID,
) gpa.Input

This message is internal one, but should be sent by other components (e.g. consensus or the chain).

func NewInputConsensusOutputSkip

func NewInputConsensusOutputSkip(
	logIndex LogIndex,
	baseAliasOutputID iotago.OutputID,
) gpa.Input

This message is internal one, but should be sent by other components (e.g. consensus or the chain).

func NewInputConsensusTimeout

func NewInputConsensusTimeout(logIndex LogIndex) gpa.Input

This message is internal one, but should be sent by other components (e.g. consensus or the chain).

func NewInputStart

func NewInputStart() gpa.Input

func NewInputSuspend

func NewInputSuspend() gpa.Input

func UnmarshalMessage

func UnmarshalMessage(data []byte) (gpa.Message, error)

Types

type CmtLog

type CmtLog interface {
	AsGPA() gpa.GPA
}

Public interface for this algorithm.

func New

func New(
	me gpa.NodeID,
	chainID isc.ChainID,
	dkShare tcrypto.DKShare,
	consensusStateRegistry ConsensusStateRegistry,
	nodeIDFromPubKey func(pubKey *cryptolib.PublicKey) gpa.NodeID,
	log *logger.Logger,
) (CmtLog, error)

Construct new node instance for this protocol.

> ON Startup: > Let prevLI <- TRY restoring the last started LogIndex ELSE 0 > MinLI <- prevLI + 1 > ...

type ConsensusStateRegistry

type ConsensusStateRegistry interface {
	Get(chainID isc.ChainID, committeeAddress iotago.Address) (*State, error) // Can return ErrCmtLogStateNotFound.
	Set(chainID isc.ChainID, committeeAddress iotago.Address, state *State) error
}

Interface used to store and recover the existing persistent state. To be implemented by the registry.

type LogIndex

type LogIndex uint32

LogIndex starts from 1. 0 is used as a nil value.

func NilLogIndex

func NilLogIndex() LogIndex

func (LogIndex) AsUint32

func (li LogIndex) AsUint32() uint32

func (LogIndex) Bytes

func (li LogIndex) Bytes() []byte

func (LogIndex) IsNil

func (li LogIndex) IsNil() bool

func (LogIndex) Next

func (li LogIndex) Next() LogIndex

type Output

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

Output for this protocol indicates, what instance of a consensus is currently required to be run. The unique identifier here is the logIndex (there will be no different baseAliasOutputs for the same logIndex).

func (*Output) GetBaseAliasOutput

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

func (*Output) GetLogIndex

func (o *Output) GetLogIndex() LogIndex

func (*Output) String

func (o *Output) String() string

type State

type State struct {
	LogIndex LogIndex
}

type VarLocalView

type VarLocalView interface {
	//
	// Returns alias output to produce next transaction on, or nil if we should wait.
	// In the case of nil, we either wait for the first AO to receive, or we are
	// still recovering from a TX rejection.
	GetBaseAliasOutput() *isc.AliasOutputWithID
	//
	// Corresponds to the `ao_received` event in the specification.
	// Returns true, if the proposed BaseAliasOutput has changed.
	AliasOutputConfirmed(confirmed *isc.AliasOutputWithID) bool
	//
	// Corresponds to the `tx_rejected` event in the specification.
	// Returns true, if the proposed BaseAliasOutput has changed.
	AliasOutputRejected(rejected *isc.AliasOutputWithID) bool
	//
	// Corresponds to the `tx_posted` event in the specification.
	// Returns true, if the proposed BaseAliasOutput has changed.
	ConsensusOutputDone(consumed iotago.OutputID, published *isc.AliasOutputWithID) bool
	//
	// Support functions.
	StatusString() string
}

func NewVarLocalView

func NewVarLocalView() VarLocalView

type VarLogIndex

type VarLogIndex interface {
	Value() (LogIndex, *isc.AliasOutputWithID)
	// StartReceived() gpa.OutMessages // TODO: Add the BaseAO parameter, or maybe it is enough to have the L1ReplacedBaseAliasOutput?
	ConsensusOutputReceived(consensusLI LogIndex, nextBaseAO *isc.AliasOutputWithID) gpa.OutMessages
	ConsensusTimeoutReceived(consensusLI LogIndex) gpa.OutMessages
	L1ReplacedBaseAliasOutput(nextBaseAO *isc.AliasOutputWithID) gpa.OutMessages
	MsgNextLogIndexReceived(msg *msgNextLogIndex) gpa.OutMessages
}

func NewVarLogIndex

func NewVarLogIndex(
	nodeIDs []gpa.NodeID,
	n int,
	f int,
	initLI LogIndex,
	log *logger.Logger,
) VarLogIndex