snowman

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 7, 2024 License: BSD-3-Clause Imports: 24 Imported by: 2

Documentation

Overview

Package snowman is a generated GoMock package.

Index

Constants

This section is empty.

Variables

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

Functions

This section is empty.

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.
	//
	// If nil is returned, it is guaranteed that either Accept or Reject will be
	// called on this block, unless the VM is shut down.
	Verify(context.Context) 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 {
	health.Checker

	// Takes in the context, snowball parameters, and the last accepted block.
	Initialize(
		ctx *snow.ConsensusContext,
		params snowball.Parameters,
		lastAcceptedID ids.ID,
		lastAcceptedHeight uint64,
		lastAcceptedTime time.Time,
	) error

	// 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(context.Context, Block) error

	// Decided returns true if the block has been decided.
	Decided(Block) bool

	// Processing returns true if the block ID is currently processing.
	Processing(ids.ID) bool

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

	// Returns the ID and height of the last accepted decision.
	LastAccepted() (ids.ID, uint64)

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

	// Returns the ID of the strongly preferred decision with the provided
	// height. Only the last accepted decision and processing decisions are
	// tracked.
	PreferenceAtHeight(height uint64) (ids.ID, bool)

	// RecordPoll collects the results of a network poll. Assumes all decisions
	// have been previously added. Returns if a critical error has occurred.
	RecordPoll(context.Context, bag.Bag[ids.ID]) error
}

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

func Trace 

func Trace(consensus Consensus, tracer trace.Tracer) Consensus

type Factory 

type Factory interface {
	New() Consensus
}

Factory returns new instances of Consensus

type MockBlock 

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

MockBlock is a mock of Block interface.

func NewMockBlock 

func NewMockBlock(ctrl *gomock.Controller) *MockBlock

NewMockBlock creates a new mock instance.

func (*MockBlock) Accept 

func (m *MockBlock) Accept(arg0 context.Context) error

Accept mocks base method.

func (*MockBlock) Bytes 

func (m *MockBlock) Bytes() []byte

Bytes mocks base method.

func (*MockBlock) EXPECT 

func (m *MockBlock) EXPECT() *MockBlockMockRecorder

EXPECT returns an object that allows the caller to indicate expected use.

func (*MockBlock) Height 

func (m *MockBlock) Height() uint64

Height mocks base method.

func (*MockBlock) ID 

func (m *MockBlock) ID() ids.ID

ID mocks base method.

func (*MockBlock) Parent 

func (m *MockBlock) Parent() ids.ID

Parent mocks base method.

func (*MockBlock) Reject 

func (m *MockBlock) Reject(arg0 context.Context) error

Reject mocks base method.

func (*MockBlock) Status 

func (m *MockBlock) Status() choices.Status

Status mocks base method.

func (*MockBlock) Timestamp 

func (m *MockBlock) Timestamp() time.Time

Timestamp mocks base method.

func (*MockBlock) Verify 

func (m *MockBlock) Verify(arg0 context.Context) error

Verify mocks base method.

type MockBlockMockRecorder 

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

MockBlockMockRecorder is the mock recorder for MockBlock.

func (*MockBlockMockRecorder) Accept 

func (mr *MockBlockMockRecorder) Accept(arg0 any) *gomock.Call

Accept indicates an expected call of Accept.

func (*MockBlockMockRecorder) Bytes 

func (mr *MockBlockMockRecorder) Bytes() *gomock.Call

Bytes indicates an expected call of Bytes.

func (*MockBlockMockRecorder) Height 

func (mr *MockBlockMockRecorder) Height() *gomock.Call

Height indicates an expected call of Height.

func (*MockBlockMockRecorder) ID 

func (mr *MockBlockMockRecorder) ID() *gomock.Call

ID indicates an expected call of ID.

func (*MockBlockMockRecorder) Parent 

func (mr *MockBlockMockRecorder) Parent() *gomock.Call

Parent indicates an expected call of Parent.

func (*MockBlockMockRecorder) Reject 

func (mr *MockBlockMockRecorder) Reject(arg0 any) *gomock.Call

Reject indicates an expected call of Reject.

func (*MockBlockMockRecorder) Status 

func (mr *MockBlockMockRecorder) Status() *gomock.Call

Status indicates an expected call of Status.

func (*MockBlockMockRecorder) Timestamp 

func (mr *MockBlockMockRecorder) Timestamp() *gomock.Call

Timestamp indicates an expected call of Timestamp.

func (*MockBlockMockRecorder) Verify 

func (mr *MockBlockMockRecorder) Verify(arg0 any) *gomock.Call

Verify indicates an expected call of Verify.

type OracleBlock 

type OracleBlock interface {
	// Options returns the possible children of this block in the order this
	// validator prefers the blocks.
	Options(context.Context) ([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

func (*TestBlock) Compare 

func (b *TestBlock) Compare(other *TestBlock) int

func (*TestBlock) Height 

func (b *TestBlock) Height() uint64

func (*TestBlock) Parent 

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

func (*TestBlock) Timestamp 

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

func (*TestBlock) Verify 

func (b *TestBlock) Verify(context.Context) error

type Topological 

type Topological struct {
	// 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) Add 

func (ts *Topological) Add(ctx context.Context, blk Block) error

func (*Topological) Decided 

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

func (*Topological) HealthCheck 

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

HealthCheck returns information about the consensus health.

func (*Topological) Initialize 

func (ts *Topological) Initialize(
	ctx *snow.ConsensusContext,
	params snowball.Parameters,
	lastAcceptedID ids.ID,
	lastAcceptedHeight uint64,
	lastAcceptedTime time.Time,
) error

func (*Topological) IsPreferred 

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

func (*Topological) LastAccepted 

func (ts *Topological) LastAccepted() (ids.ID, uint64)

func (*Topological) NumProcessing 

func (ts *Topological) NumProcessing() int

func (*Topological) Preference 

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

func (*Topological) PreferenceAtHeight 

func (ts *Topological) PreferenceAtHeight(height uint64) (ids.ID, bool)

func (*Topological) Processing 

func (ts *Topological) Processing(blkID ids.ID) bool

func (*Topological) RecordPoll 

func (ts *Topological) RecordPoll(ctx context.Context, voteBag bag.Bag[ids.ID]) error

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 preference 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 = 4 * |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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.