snowman

Documentation

Index

• Variables
• func SortTestBlocks(blocks []*TestBlock)
• type Block
• type Consensus
• type Factory
• type OracleBlock
• type TestBlock
  • func (b *TestBlock) Bytes() []byte
  • func (b *TestBlock) Height() uint64
  • func (b *TestBlock) Parent() ids.ID
  • func (b *TestBlock) Timestamp() time.Time
  • func (b *TestBlock) Verify() error
• type Topological
  • func (ts *Topological) AcceptedOrProcessing(blk Block) bool
  • func (ts *Topological) Add(blk Block) error
  • func (ts *Topological) DecidedOrProcessing(blk Block) bool
  • func (ts *Topological) Finalized() bool
  • func (ts *Topological) HealthCheck() (interface{}, error)
  • func (ts *Topological) Initialize(ctx *snow.Context, params snowball.Parameters, rootID ids.ID, ...) error
  • func (ts *Topological) IsPreferred(blk Block) bool
  • func (ts *Topological) NumProcessing() int
  • func (ts *Topological) Parameters() snowball.Parameters
  • func (ts *Topological) Preference() ids.ID
  • func (ts *Topological) RecordPoll(voteBag ids.Bag) error
• type TopologicalFactory
  • func (TopologicalFactory) New() Consensus

Variables

var ErrNotOracle = errors.New("block isn't an oracle")

Functions

func SortTestBlocks

func SortTestBlocks(blocks []*TestBlock)

SortTestBlocks sorts the array of blocks by height

Types

type Block

type Block interface {
	choices.Decidable

	// Parent returns the ID of this block's parent.
	Parent() ids.ID

	// Verify that the state transition this block would make if accepted is
	// valid. If the state transition is invalid, a non-nil error should be
	// returned.
	//
	// It is guaranteed that the Parent has been successfully verified.
	Verify() error

	// Bytes returns the binary representation of this block.
	//
	// This is used for sending blocks to peers. The bytes should be able to be
	// parsed into the same block on another node.
	Bytes() []byte

	// Height returns the height of this block in the chain.
	Height() uint64

	// Time this block was proposed at. This value should be consistent across
	// all nodes. If this block hasn't been successfully verified, any value can
	// be returned. If this block is the last accepted block, the timestamp must
	// be returned correctly. Otherwise, accepted blocks can return any value.
	Timestamp() time.Time
}

Block is a possible decision that dictates the next canonical block.

Blocks are guaranteed to be Verified, Accepted, and Rejected in topological order. Specifically, if Verify is called, then the parent has already been verified. If Accept is called, then the parent has already been accepted. If Reject is called, the parent has already been accepted or rejected.

If the status of the block is Unknown, ID is assumed to be able to be called. If the status of the block is Accepted or Rejected; Parent, Verify, Accept, and Reject will never be called.

type Consensus

type Consensus interface {
	// Takes in the context, snowball parameters, and the last accepted block.
	Initialize(
		ctx *snow.Context,
		params snowball.Parameters,
		lastAcceptedID ids.ID,
		lastAcceptedHeight uint64,
	) error

	// Returns the parameters that describe this snowman instance
	Parameters() snowball.Parameters

	// Returns the number of blocks processing
	NumProcessing() int

	// Adds a new decision. Assumes the dependency has already been added.
	// Returns if a critical error has occurred.
	Add(Block) error

	// AcceptedOrProcessing returns true if the block has been accepted or is
	// currently processing
	AcceptedOrProcessing(Block) bool

	// DecidedOrProcessing returns true if the block has been decided or is
	// currently processing.
	DecidedOrProcessing(Block) bool

	// IsPreferred returns true if the block is currently on the preferred
	// chain.
	IsPreferred(Block) bool

	// Returns the ID of the tail of the strongly preferred sequence of
	// decisions.
	Preference() ids.ID

	// RecordPoll collects the results of a network poll. Assumes all decisions
	// have been previously added. Returns if a critical error has occurred.
	RecordPoll(ids.Bag) error

	// Finalized returns true if all decisions that have been added have been
	// finalized. Note, it is possible that after returning finalized, a new
	// decision may be added such that this instance is no longer finalized.
	Finalized() bool

	// HealthCheck returns information about the consensus health.
	HealthCheck() (interface{}, error)
}

Consensus represents a general snowman instance that can be used directly to process a series of dependent operations.

type Factory

type Factory interface {
	New() Consensus
}

Factory returns new instances of Consensus

type OracleBlock

type OracleBlock interface {
	Block

	// Options returns the possible children of this block in the order this
	// validator prefers the blocks.
	Options() ([2]Block, error)
}

OracleBlock is a block that only has two valid children. The children should be returned in preferential order.

This ordering does not need to be deterministically created from the chain state.

type TestBlock

type TestBlock struct {
	choices.TestDecidable

	ParentV    ids.ID
	HeightV    uint64
	TimestampV time.Time
	VerifyV    error
	BytesV     []byte
}

TestBlock is a useful test block

func (*TestBlock) Bytes

func (b *TestBlock) Bytes() []byte

Bytes implements the Block interface

func (*TestBlock) Height

func (b *TestBlock) Height() uint64

Height returns the height of the block

func (*TestBlock) Parent

func (b *TestBlock) Parent() ids.ID

Parent implements the Block interface

func (*TestBlock) Timestamp

func (b *TestBlock) Timestamp() time.Time

Timestamp returns the time of the block

func (*TestBlock) Verify

func (b *TestBlock) Verify() error

Verify implements the Block interface

type Topological

type Topological struct {
	metrics.Latency
	metrics.Polls
	// contains filtered or unexported fields
}

Topological implements the Snowman interface by using a tree tracking the strongly preferred branch. This tree structure amortizes network polls to vote on more than just the next block.

func (*Topological) AcceptedOrProcessing

func (ts *Topological) AcceptedOrProcessing(blk Block) bool

AcceptedOrProcessing implements the Snowman interface

func (*Topological) Add

func (ts *Topological) Add(blk Block) error

Add implements the Snowman interface

func (*Topological) DecidedOrProcessing

func (ts *Topological) DecidedOrProcessing(blk Block) bool

DecidedOrProcessing implements the Snowman interface

func (*Topological) Finalized

func (ts *Topological) Finalized() bool

Finalized implements the Snowman interface

func (*Topological) HealthCheck

func (ts *Topological) HealthCheck() (interface{}, error)

HealthCheck returns information about the consensus health.

func (*Topological) Initialize

func (ts *Topological) Initialize(ctx *snow.Context, params snowball.Parameters, rootID ids.ID, rootHeight uint64) error

Initialize implements the Snowman interface

func (*Topological) IsPreferred

func (ts *Topological) IsPreferred(blk Block) bool

IsPreferred implements the Snowman interface

func (*Topological) NumProcessing

func (ts *Topological) NumProcessing() int

NumProcessing implements the Snowman interface

func (*Topological) Parameters

func (ts *Topological) Parameters() snowball.Parameters

Parameters implements the Snowman interface

func (*Topological) Preference

func (ts *Topological) Preference() ids.ID

Preference implements the Snowman interface

func (*Topological) RecordPoll

func (ts *Topological) RecordPoll(voteBag ids.Bag) error

RecordPoll implements the Snowman interface

The votes bag contains at most K votes for blocks in the tree. If there is a vote for a block that isn't in the tree, the vote is dropped.

Votes are propagated transitively towards the genesis. All blocks in the tree that result in at least Alpha votes will record the poll on their children. Every other block will have an unsuccessful poll registered.

After collecting which blocks should be voted on, the polls are registered and blocks are accepted/rejected as needed. The tail is then updated to equal the leaf on the preferred branch.

To optimize the theoretical complexity of the vote propagation, a topological sort is done over the blocks that are reachable from the provided votes. During the sort, votes are pushed towards the genesis. To prevent interating over all blocks that had unsuccessful polls, we set a flag on the block to know that any future traversal through that block should register an unsuccessful poll on that block and every descendant block.

The complexity of this function is: - Runtime = 3 * |live set| + |votes| - Space = 2 * |live set| + |votes|

type TopologicalFactory

type TopologicalFactory struct{}

TopologicalFactory implements Factory by returning a topological struct

func (TopologicalFactory) New

func (TopologicalFactory) New() Consensus

New implements Factory