tipmanager

Documentation

Index

• Variables
• type Events
• type TipManager
• type TipMetadata
• type TipPool
  • func (t TipPool) Max(other TipPool) TipPool
  • func (t TipPool) String() string

Variables

var NewEvents = event.CreateGroupConstructor(func() *Events {
	return &Events{
		BlockAdded: event.New1[TipMetadata](),
	}
})

NewEvents creates a new Events instance.

Types

type Events

type Events struct {
	// BlockAdded gets triggered when a new block was added to the TipManager.
	BlockAdded *event.Event1[TipMetadata]
	// Group makes the Events linkable through the central Events dictionary.
	event.Group[Events, *Events]
}

Events represents events happening in the TipManager.

type TipManager

type TipManager interface {
	// AddBlock adds a block to the TipManager.
	AddBlock(block *blocks.Block) TipMetadata

	// OnBlockAdded registers a callback that is triggered whenever a new Block was added to the TipManager.
	OnBlockAdded(handler func(block TipMetadata)) (unsubscribe func())

	// AddSeat adds a validator seat to the tracking of the TipManager.
	AddSeat(seat account.SeatIndex)

	// RemoveSeat removes a validator seat from the tracking of the TipManager.
	RemoveSeat(seat account.SeatIndex)

	// ValidationTips returns the validation tips of the TipManager (with an optional limit).
	ValidationTips(optAmount ...int) []TipMetadata

	// StrongTips returns the strong tips of the TipManager (with an optional limit).
	StrongTips(optAmount ...int) []TipMetadata

	// WeakTips returns the weak tips of the TipManager (with an optional limit).
	WeakTips(optAmount ...int) []TipMetadata

	// Evict evicts a block from the TipManager.
	Evict(slot iotago.SlotIndex)

	// Reset resets the component to a clean state as if it was created at the last commitment.
	Reset()

	// Interface embeds the required methods of the module.Module.
	module.Module
}

TipManager is a component that maintains a perception of the unreferenced Blocks of the Tangle.

Blocks in the TipManager can be classified to belong to a TipPool which defines how the tip selection strategy will treat them:

- StrongTipPool: The block will be referenced via strong parents. - WeakTipPool: The block will be referenced via weak parents. - DroppedTipPool: The block will be ignored by the tip selection strategy.

The TipManager itself does not classify the blocks, but rather provides a framework to do so. Blocks initially start out with an UndefinedTipPool, which causes the block to be temporarily ignored by the tip selection strategy.

The unreferenced blocks of a TipPool form the actual Tips which are used by the tip selection strategy to construct new Blocks.

type TipMetadata

type TipMetadata interface {
	// ID returns the identifier of the block the TipMetadata belongs to.
	ID() iotago.BlockID

	// Block returns the block that the TipMetadata belongs to.
	Block() *blocks.Block

	// TipPool exposes a variable that stores the current TipPool of the block.
	TipPool() reactive.Variable[TipPool]

	// IsStrongTip returns a ReadableVariable that indicates if the block is a strong tip.
	IsStrongTip() reactive.ReadableVariable[bool]

	// IsWeakTip returns a ReadableVariable that indicates if the block is a weak tip.
	IsWeakTip() reactive.ReadableVariable[bool]

	// IsOrphaned returns a ReadableVariable that indicates if the block was orphaned.
	IsOrphaned() reactive.ReadableVariable[bool]

	// LivenessThresholdReached exposes an event that is triggered when the liveness threshold is reached.
	LivenessThresholdReached() reactive.Event

	// Evicted exposes an event that is triggered when the block is evicted.
	Evicted() reactive.Event

	String() string
}

TipMetadata allows to access the tip related metadata and events of a block in the TipManager.

type TipPool

type TipPool uint8

TipPool represents a pool of blocks that are treated in a certain way by the tip selection strategy.

const (
	// UndefinedTipPool is the zero value of TipPool.
	UndefinedTipPool TipPool = iota

	// StrongTipPool represents a pool of blocks that are supposed to be referenced through strong parents.
	StrongTipPool

	// WeakTipPool represents a pool of blocks that are supposed to be referenced through weak parents.
	WeakTipPool

	// DroppedTipPool represents a pool of blocks that are supposed to be ignored by the tip selection strategy.
	DroppedTipPool
)

func (TipPool) Max

func (t TipPool) Max(other TipPool) TipPool

Max returns the maximum of the two TipPools.

func (TipPool) String

func (t TipPool) String() string

String returns a human-readable representation of the TipPool.