whiteflag

Documentation

Index

• Variables
• func ConfirmMilestone(utxoManager *utxo.Manager, parentsTraverserStorage dag.ParentsTraverserStorage, ...) (*ConfirmedMilestoneStats, *ConfirmationMetrics, error)
• type CheckBlockReferencedFunc
• type Confirmation
• type ConfirmationMetrics
• type ConfirmedMilestoneStats
• type ReferencedBlock
• type ReferencedBlocks
  • func (b ReferencedBlocks) BlockIDs() iotago.BlockIDs
  • func (b ReferencedBlocks) ConflictingTransactionBlockIDs() iotago.BlockIDs
  • func (b ReferencedBlocks) IncludedTransactionBlockIDs() iotago.BlockIDs
  • func (b ReferencedBlocks) NonTransactionBlockIDs() iotago.BlockIDs
• type SetBlockReferencedFunc
• type WhiteFlagMutations
  • func ComputeWhiteFlagMutations(ctx context.Context, utxoManager *utxo.Manager, ...) (*WhiteFlagMutations, error)

Variables

var (
	DefaultCheckBlockReferencedFunc = func(meta *storage.BlockMetadata) bool {
		return meta.IsReferenced()
	}
	DefaultSetBlockReferencedFunc = func(meta *storage.BlockMetadata, referenced bool, msIndex iotago.MilestoneIndex, wfIndex uint32) {
		meta.SetReferenced(referenced, msIndex, wfIndex)
	}
)

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

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

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

Functions

func ConfirmMilestone

func ConfirmMilestone(
	utxoManager *utxo.Manager,
	parentsTraverserStorage dag.ParentsTraverserStorage,
	cachedBlockFunc storage.CachedBlockFunc,
	protoParams *iotago.ProtocolParameters,
	genesisMilestoneIndex iotago.MilestoneIndex,
	milestonePayload *iotago.Milestone,
	whiteFlagTraversalCondition dag.Predicate,
	checkBlockReferencedFunc CheckBlockReferencedFunc,
	setBlockReferencedFunc SetBlockReferencedFunc,
	serverMetrics *metrics.ServerMetrics,
	onValidateReceipt func(r *utxo.ReceiptTuple) error,
	onMilestoneConfirmed func(confirmation *Confirmation),
	forEachReferencedBlock func(blockMetadata *storage.CachedMetadata, index iotago.MilestoneIndex, confTime uint32),
	onLedgerUpdated func(index iotago.MilestoneIndex, newOutputs utxo.Outputs, newSpents utxo.Spents),
	onTreasuryMutated func(index iotago.MilestoneIndex, tuple *utxo.TreasuryMutationTuple),
) (*ConfirmedMilestoneStats, *ConfirmationMetrics, error)

ConfirmMilestone traverses a milestone and collects all unreferenced blocks, then the ledger diffs are calculated, the ledger state is checked and all blocks 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 CheckBlockReferencedFunc

type CheckBlockReferencedFunc func(meta *storage.BlockMetadata) bool

type Confirmation

type Confirmation struct {
	// The index of the milestone that got confirmed.
	MilestoneIndex iotago.MilestoneIndex
	// The milestone ID of the milestone that got confirmed.
	MilestoneID iotago.MilestoneID
	// The parents of the milestone that got confirmed.
	MilestoneParents iotago.BlockIDs
	// The ledger mutations and referenced blocks 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
	DurationApplyConfirmation              time.Duration
	DurationOnMilestoneConfirmed           time.Duration
	DurationLedgerUpdated                  time.Duration
	DurationTreasuryMutated                time.Duration
	DurationSetConfirmedMilestoneIndex     time.Duration
	DurationUpdateConeRootIndexes          time.Duration
	DurationConfirmedMilestoneChanged      time.Duration
	DurationConfirmedMilestoneIndexChanged time.Duration
	DurationTotal                          time.Duration
}

ConfirmationMetrics holds metrics about a confirmation run.

type ConfirmedMilestoneStats

type ConfirmedMilestoneStats struct {
	Index                                     iotago.MilestoneIndex
	ConfirmationTime                          int64
	BlocksReferenced                          int
	BlocksExcludedWithConflictingTransactions int
	BlocksIncludedWithTransactions            int
	BlocksExcludedWithoutTransactions         int
}

type ReferencedBlock

type ReferencedBlock struct {
	BlockID       iotago.BlockID
	IsTransaction bool
	Conflict      storage.Conflict
}

type ReferencedBlocks

type ReferencedBlocks []ReferencedBlock

func (ReferencedBlocks) BlockIDs

func (b ReferencedBlocks) BlockIDs() iotago.BlockIDs

func (ReferencedBlocks) ConflictingTransactionBlockIDs

func (b ReferencedBlocks) ConflictingTransactionBlockIDs() iotago.BlockIDs

func (ReferencedBlocks) IncludedTransactionBlockIDs

func (b ReferencedBlocks) IncludedTransactionBlockIDs() iotago.BlockIDs

func (ReferencedBlocks) NonTransactionBlockIDs

func (b ReferencedBlocks) NonTransactionBlockIDs() iotago.BlockIDs

type SetBlockReferencedFunc

type SetBlockReferencedFunc func(meta *storage.BlockMetadata, referenced bool, msIndex iotago.MilestoneIndex, wfIndex uint32)

type WhiteFlagMutations

type WhiteFlagMutations struct {
	// The blocks which were referenced by the milestone
	ReferencedBlocks ReferencedBlocks
	// Contains the newly created Unspent Outputs by the given confirmation.
	NewOutputs map[iotago.OutputID]*utxo.Output
	// Contains the Spent Outputs for the given confirmation.
	NewSpents map[iotago.OutputID]*utxo.Spent
	// The merkle tree root hash of all referenced blocks in the past cone.
	InclusionMerkleRoot [iotago.MilestoneMerkleProofLength]byte
	// The merkle tree root hash of all included transaction blocks.
	AppliedMerkleRoot [iotago.MilestoneMerkleProofLength]byte
}

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

func ComputeWhiteFlagMutations

func ComputeWhiteFlagMutations(ctx context.Context,
	utxoManager *utxo.Manager,
	parentsTraverser *dag.ParentsTraverser,
	cachedBlockFunc storage.CachedBlockFunc,
	msIndex iotago.MilestoneIndex,
	msTimestamp uint32,
	parents iotago.BlockIDs,
	previousMilestoneID iotago.MilestoneID,
	genesisMilestoneIndex iotago.MilestoneIndex,
	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 blocks of the given cone are traversed and in their corresponding order applied/mutated against the previous ledger state, respectively previous applied mutations. Blocks within the approving cone must be valid. Blocks 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 blocks 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.