whiteflag

Documentation

Index

• Constants
• Variables
• func ConfirmMilestone(utxoManager *utxo.Manager, parentsTraverserStorage dag.ParentsTraverserStorage, ...) (*ConfirmedMilestoneStats, *ConfirmationMetrics, error)
• type CheckMessageReferencedFunc
• type Confirmation
• type ConfirmationMetrics
• type ConfirmedMilestoneStats
• type Hasher
  • func NewHasher(h crypto.Hash) *Hasher
  • func (t *Hasher) EmptyRoot() []byte
  • func (t *Hasher) Hash(data []encoding.BinaryMarshaler) ([]byte, error)
  • func (t *Hasher) Size() int
• type MessageWithConflict
• type SetMessageReferencedFunc
• type WhiteFlagMutations
  • func ComputeWhiteFlagMutations(ctx context.Context, utxoManager *utxo.Manager, ...) (*WhiteFlagMutations, error)

Constants

const (
	LeafHashPrefix = 0
	NodeHashPrefix = 1
)

Domain separation prefixes

Variables

var (
	DefaultCheckMessageReferencedFunc = func(meta *storage.MessageMetadata) bool {
		return meta.IsReferenced()
	}
	DefaultSetMessageReferencedFunc = func(meta *storage.MessageMetadata, referenced bool, msIndex milestone.Index) {
		meta.SetReferenced(referenced, msIndex)
	}
)

var (
	// ErrIncludedMessagesSumDoesntMatch is returned when the sum of the included messages a milestone approves does not match the referenced messages minus the excluded messages.
	ErrIncludedMessagesSumDoesntMatch = errors.New("the sum of the included messages doesn't match the referenced messages minus the excluded messages")

	// traversal stops if no more messages pass the given condition
	// Caution: condition func is not in DFS order
	DefaultWhiteFlagTraversalCondition = func(cachedMsgMeta *storage.CachedMetadata) (bool, error) {
		defer cachedMsgMeta.Release(true)

		return !cachedMsgMeta.Metadata().IsReferenced(), nil
	}
)

Functions

func ConfirmMilestone

func ConfirmMilestone(
	utxoManager *utxo.Manager,
	parentsTraverserStorage dag.ParentsTraverserStorage,
	cachedMessageFunc storage.CachedMessageFunc,
	milestoneMessageID hornet.MessageID,
	whiteFlagTraversalCondition dag.Predicate,
	checkMessageReferencedFunc CheckMessageReferencedFunc,
	setMessageReferencedFunc SetMessageReferencedFunc,
	serverMetrics *metrics.ServerMetrics,
	forEachReferencedMessage func(messageMetadata *storage.CachedMetadata, index milestone.Index, confTime uint64),
	onMilestoneConfirmed func(confirmation *Confirmation),
	onLedgerUpdated func(index milestone.Index, newOutputs utxo.Outputs, newSpents utxo.Spents),
	forEachNewOutput func(index milestone.Index, output *utxo.Output),
	forEachNewSpent func(index milestone.Index, spent *utxo.Spent),
	onReceipt func(r *utxo.ReceiptTuple) error) (*ConfirmedMilestoneStats, *ConfirmationMetrics, error)

ConfirmMilestone traverses a milestone and collects all unreferenced msg, then the ledger diffs are calculated, the ledger state is checked and all msg are marked as referenced. Additionally, this function also examines the milestone for a receipt and generates new migrated outputs if one is present. The treasury is mutated accordingly.

Types

type CheckMessageReferencedFunc

type CheckMessageReferencedFunc func(meta *storage.MessageMetadata) bool

type Confirmation

type Confirmation struct {
	// The index of the milestone that got confirmed.
	MilestoneIndex milestone.Index
	// The message ID of the milestone that got confirmed.
	MilestoneMessageID hornet.MessageID
	// The ledger mutations and referenced messages of this milestone.
	Mutations *WhiteFlagMutations
}

Confirmation represents a confirmation done via a milestone under the "white-flag" approach.

type ConfirmationMetrics

type ConfirmationMetrics struct {
	DurationWhiteflag                                time.Duration
	DurationReceipts                                 time.Duration
	DurationConfirmation                             time.Duration
	DurationLedgerUpdated                            time.Duration
	DurationApplyIncludedWithTransactions            time.Duration
	DurationApplyExcludedWithoutTransactions         time.Duration
	DurationApplyMilestone                           time.Duration
	DurationApplyExcludedWithConflictingTransactions time.Duration
	DurationForEachNewOutput                         time.Duration
	DurationForEachNewSpent                          time.Duration
	DurationOnMilestoneConfirmed                     time.Duration
	DurationSetConfirmedMilestoneIndex               time.Duration
	DurationUpdateConeRootIndexes                    time.Duration
	DurationConfirmedMilestoneChanged                time.Duration
	DurationConfirmedMilestoneIndexChanged           time.Duration
	DurationMilestoneConfirmedSyncEvent              time.Duration
	DurationMilestoneConfirmed                       time.Duration
	DurationTotal                                    time.Duration
}

ConfirmationMetrics holds metrics about a confirmation run.

type ConfirmedMilestoneStats

type ConfirmedMilestoneStats struct {
	Index                                       milestone.Index
	ConfirmationTime                            int64
	MessagesReferenced                          int
	MessagesExcludedWithConflictingTransactions int
	MessagesIncludedWithTransactions            int
	MessagesExcludedWithoutTransactions         int
}

type Hasher

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

Hasher implements the hashing algorithm described in the IOTA protocol RFC-12.

func NewHasher

func NewHasher(h crypto.Hash) *Hasher

NewHasher creates a new Hasher using the provided hash function.

func (*Hasher) EmptyRoot

func (t *Hasher) EmptyRoot() []byte

EmptyRoot returns a special case for an empty tree. This is equivalent to Hash(nil).

func (*Hasher) Hash

func (t *Hasher) Hash(data []encoding.BinaryMarshaler) ([]byte, error)

Hash computes the Merkle tree hash of the provided data encodings.

func (*Hasher) Size

func (t *Hasher) Size() int

Size returns the length, in bytes, of a digest resulting from the given hash function.

type MessageWithConflict

type MessageWithConflict struct {
	MessageID hornet.MessageID
	Conflict  storage.Conflict
}

type SetMessageReferencedFunc

type SetMessageReferencedFunc func(meta *storage.MessageMetadata, referenced bool, msIndex milestone.Index)

type WhiteFlagMutations

type WhiteFlagMutations struct {
	// The messages which mutate the ledger in the order in which they were applied.
	MessagesIncludedWithTransactions hornet.MessageIDs
	// The messages which were excluded as they were conflicting with the mutations.
	MessagesExcludedWithConflictingTransactions []MessageWithConflict
	// The messages which were excluded because they did not include a value transaction.
	MessagesExcludedWithoutTransactions hornet.MessageIDs
	// The messages which were referenced by the milestone (should be the sum of MessagesIncludedWithTransactions + MessagesExcludedWithConflictingTransactions + MessagesExcludedWithoutTransactions).
	MessagesReferenced hornet.MessageIDs
	// Contains the newly created Unspent Outputs by the given confirmation.
	NewOutputs map[string]*utxo.Output
	// Contains the Spent Outputs for the given confirmation.
	NewSpents map[string]*utxo.Spent

	// The merkle tree root hash of all messages.
	MerkleTreeHash [iotago.MilestoneInclusionMerkleProofLength]byte
	// contains filtered or unexported fields
}

WhiteFlagMutations contains the ledger mutations and referenced messages applied to a cone under the "white-flag" approach.

func ComputeWhiteFlagMutations

func ComputeWhiteFlagMutations(ctx context.Context,
	utxoManager *utxo.Manager,
	parentsTraverser *dag.ParentsTraverser,
	cachedMessageFunc storage.CachedMessageFunc,
	msIndex milestone.Index,
	parents hornet.MessageIDs,
	traversalCondition dag.Predicate) (*WhiteFlagMutations, error)

ComputeWhiteFlagMutations computes the ledger changes in accordance to the white-flag rules for the cone referenced by the parents. Via a post-order depth-first search the approved messages of the given cone are traversed and in their corresponding order applied/mutated against the previous ledger state, respectively previous applied mutations. Messages within the approving cone must be valid. Messages causing conflicts are ignored but do not create an error. It also computes the merkle tree root hash consisting out of the IDs of the messages which are part of the set which mutated the ledger state when applying the white-flag approach. The ledger state must be write locked while this function is getting called in order to ensure consistency.