hare

package
v0.2.26-beta.0 Latest Latest
Warning

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

 Go to latest Published: Mar 31, 2023 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

Package hare implements the Hare Protocol.

nolint

Index

Constants

View Source 
const (
	// RoundsPerIteration is the number of rounds per iteration in the hare protocol.
	RoundsPerIteration = 4
)
View Source 
const Wakeup = math.MaxUint32 - 1 // -2

Wakeup has a value of -2 because it occurs exactly two round durations before the end of round 0. This accounts for the duration of round zero and the preround.

Variables

View Source 
var ErrTooLate = errors.New("consensus process finished too late")

ErrTooLate means that the consensus was terminated too late.

Functions

This section is empty.

Types

type AggregatedMessages added in v1.0.0 

type AggregatedMessages struct {
	Messages []Message `scale:"max=1000"` // limited by hare config parameter N with safety margin
}

AggregatedMessages is a collection of messages.

func (*AggregatedMessages) DecodeScale added in v1.0.0 

func (t *AggregatedMessages) DecodeScale(dec *scale.Decoder) (total int, err error)

func (*AggregatedMessages) EncodeScale added in v1.0.0 

func (t *AggregatedMessages) EncodeScale(enc *scale.Encoder) (total int, err error)

type Broker 

type Broker struct {
	log.Log
	// contains filtered or unexported fields
}

Broker is the dispatcher of incoming Hare messages. The broker validates that the sender is eligible and active and forwards the message to the corresponding outbox.

func (*Broker) Close added in v1.0.0 

func (b *Broker) Close()

Close closes broker.

func (*Broker) HandleEligibility added in v1.0.0 

func (b *Broker) HandleEligibility(ctx context.Context, em *types.HareEligibilityGossip) bool

func (*Broker) HandleMessage added in v1.0.0 

func (b *Broker) HandleMessage(ctx context.Context, _ p2p.Peer, msg []byte) pubsub.ValidationResult

HandleMessage separate listener routine that receives gossip messages and adds them to the priority queue.

func (*Broker) Register 

func (b *Broker) Register(ctx context.Context, id types.LayerID) (chan any, error)

Register a layer to receive messages Note: the registering instance is assumed to be started and accepting messages.

func (*Broker) Start 

func (b *Broker) Start(ctx context.Context)

Start listening to Hare messages (non-blocking).

func (*Broker) Synced added in v0.1.2 

func (b *Broker) Synced(ctx context.Context, id types.LayerID) bool

Synced returns true if the given layer is synced, false otherwise.

func (*Broker) Unregister 

func (b *Broker) Unregister(ctx context.Context, id types.LayerID)

Unregister a layer from receiving messages.

type Certificate added in v1.0.0 

type Certificate struct {
	Values  []types.ProposalID `scale:"max=500"` // the committed set S - expected are 50 proposals per layer + safety margin
	AggMsgs *AggregatedMessages
}

Certificate is a collection of messages and the set of values. Typically used as a collection of commit messages.

func (*Certificate) DecodeScale added in v1.0.0 

func (t *Certificate) DecodeScale(dec *scale.Decoder) (total int, err error)

func (*Certificate) EncodeScale added in v1.0.0 

func (t *Certificate) EncodeScale(enc *scale.Encoder) (total int, err error)

type Consensus 

type Consensus interface {
	ID() types.LayerID
	Start()
	Stop()
}

Consensus represents an item that acts like a consensus process.

type CountInfo added in v1.0.0 

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

func (*CountInfo) Add added in v1.0.0 

func (ci *CountInfo) Add(other *CountInfo) *CountInfo

func (*CountInfo) IncDishonest added in v1.0.0 

func (ci *CountInfo) IncDishonest(count uint16)

func (*CountInfo) IncHonest added in v1.0.0 

func (ci *CountInfo) IncHonest(count uint16)

func (*CountInfo) IncKnownEquivocator added in v1.0.0 

func (ci *CountInfo) IncKnownEquivocator(count uint16)

func (*CountInfo) MarshalLogObject added in v1.0.0 

func (ci *CountInfo) MarshalLogObject(encoder log.ObjectEncoder) error

func (*CountInfo) Meet added in v1.0.0 

func (ci *CountInfo) Meet(threshold int) bool

type Cred added in v1.0.0 

type Cred struct {
	Count  uint16
	Honest bool
}

type EligibilityTracker added in v1.0.0 

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

func NewEligibilityTracker added in v1.0.0 

func NewEligibilityTracker(size int) *EligibilityTracker

func (*EligibilityTracker) ForEach added in v1.0.0 

func (et *EligibilityTracker) ForEach(round uint32, apply func(types.NodeID, *Cred))

func (*EligibilityTracker) Track added in v1.0.0 

func (et *EligibilityTracker) Track(nodeID types.NodeID, round uint32, count uint16, honest bool)

type Hare 

type Hare struct {
	log.Log
	// contains filtered or unexported fields
}

Hare is the orchestrator that starts new consensus processes and collects their output.

func New 

func New(
	cdb *datastore.CachedDB,
	conf config.Config,
	publisher pubsub.PublishSubsciber,
	sign *signing.EdSigner,
	pke *signing.PubKeyExtractor,
	nid types.NodeID,
	ch chan LayerOutput,
	syncState system.SyncStateProvider,
	beacons system.BeaconGetter,
	rolacle Rolacle,
	patrol layerPatrol,
	stateQ stateQuerier,
	layerClock LayerClock,
	logger log.Log,
	opts ...Opt,
) *Hare

New returns a new Hare struct.

func (*Hare) Close added in v1.0.0 

func (h *Hare) Close()

Close sends a termination signal to hare goroutines and waits for their termination.

func (*Hare) GetHareMsgHandler added in v1.0.0 

func (h *Hare) GetHareMsgHandler() pubsub.GossipHandler

GetHareMsgHandler returns the gossip handler for hare protocol message.

func (*Hare) HandleEligibility added in v1.0.0 

func (h *Hare) HandleEligibility(ctx context.Context, emsg *types.HareEligibilityGossip)

func (*Hare) Start 

func (h *Hare) Start(ctx context.Context) error

Start starts listening for layers and outputs.

type InnerMessage added in v1.0.0 

type InnerMessage struct {
	Type           MessageType
	CommittedRound uint32              // the round Values (S) is committed (Ki)
	Values         []types.ProposalID  `scale:"max=500"` // the set S. optional for commit InnerMsg in a certificate - expected are 50 proposals per layer + safety margin
	Svp            *AggregatedMessages // optional. only for proposal Messages
	Cert           *Certificate        // optional
}

InnerMessage is the actual set of fields that describe a message in the Hare protocol.

func (*InnerMessage) DecodeScale added in v1.0.0 

func (t *InnerMessage) DecodeScale(dec *scale.Decoder) (total int, err error)

func (*InnerMessage) EncodeScale added in v1.0.0 

func (t *InnerMessage) EncodeScale(enc *scale.Encoder) (total int, err error)

func (*InnerMessage) HashBytes added in v1.0.0 

func (im *InnerMessage) HashBytes() []byte

HashBytes returns the message as bytes.

func (*InnerMessage) MarshalLogObject added in v1.0.0 

func (im *InnerMessage) MarshalLogObject(encoder log.ObjectEncoder) error

type LayerClock added in v1.0.0 

type LayerClock interface {
	LayerToTime(types.LayerID) time.Time
	AwaitLayer(types.LayerID) chan struct{}
	CurrentLayer() types.LayerID
}

LayerClock provides a timer for the start of a given layer, as well as the current layer and allows converting a layer number to a clock time.

type LayerOutput added in v1.0.0 

type LayerOutput struct {
	Ctx       context.Context
	Layer     types.LayerID
	Proposals []types.ProposalID
}

LayerOutput is the output of each hare consensus process.

type Message 

type Message struct {
	types.HareMetadata
	// signature over Metadata
	Signature   types.EdSignature
	InnerMsg    *InnerMessage
	Eligibility types.HareEligibility
}

func MessageFromBuffer 

func MessageFromBuffer(buf []byte) (Message, error)

MessageFromBuffer builds an Hare message from the provided bytes buffer. It returns an error if unmarshal of the provided byte slice failed.

func (*Message) DecodeScale added in v1.0.0 

func (t *Message) DecodeScale(dec *scale.Decoder) (total int, err error)

func (*Message) EncodeScale added in v1.0.0 

func (t *Message) EncodeScale(enc *scale.Encoder) (total int, err error)

func (*Message) Field added in v0.1.27 

func (m *Message) Field() log.Field

Field returns a log field. Implements the LoggableField interface.

func (*Message) MarshalLogObject added in v1.0.0 

func (m *Message) MarshalLogObject(encoder log.ObjectEncoder) error

func (*Message) SetMetadata 

func (m *Message) SetMetadata()

func (*Message) SignedBytes added in v1.0.0 

func (m *Message) SignedBytes() []byte

SignedBytes returns the signed data for hare message.

type MessageType added in v1.0.0 

type MessageType byte

MessageType is a message type.

func (MessageType) String added in v1.0.0 

func (mType MessageType) String() string

type Msg 

type Msg struct {
	Message
	NodeID types.NodeID
}

Msg is the wrapper of the protocol's message. Messages are sent as type Message. Upon receiving, the NodeID is added to this wrapper (public key extraction).

func (*Msg) Bytes 

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

Bytes returns the message as bytes (without the public key). It panics if the message erred on unmarshal.

type Opt added in v1.0.0 

type Opt func(*Hare)

Opt for configuring beacon protocol.

type RefCountTracker 

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

RefCountTracker tracks the number of references of any object id.

func NewRefCountTracker 

func NewRefCountTracker(round uint32, et *EligibilityTracker, expectedSize int) *RefCountTracker

NewRefCountTracker creates a new reference count tracker.

func (*RefCountTracker) CountStatus 

func (rt *RefCountTracker) CountStatus(id any) *CountInfo

CountStatus returns the number of references to the given id.

func (*RefCountTracker) Track 

func (rt *RefCountTracker) Track(id any, nodeID types.NodeID)

Track increases the count for the given object id.

type Rolacle 

type Rolacle interface {
	Validate(context.Context, types.LayerID, uint32, int, types.NodeID, types.VrfSignature, uint16) (bool, error)
	CalcEligibility(context.Context, types.LayerID, uint32, int, types.NodeID, types.VRFPostIndex, types.VrfSignature) (uint16, error)
	Proof(context.Context, types.VRFPostIndex, types.LayerID, uint32) (types.VrfSignature, error)
	IsIdentityActiveOnConsensusView(context.Context, types.NodeID, types.LayerID) (bool, error)
}

Rolacle is the roles oracle provider.

type RoundClock added in v1.0.0 

type RoundClock interface {
	AwaitWakeup() <-chan struct{}
	// RoundEnd returns the time at which round ends, passing round-1 will
	// return the time at which round starts.
	RoundEnd(round uint32) time.Time
	AwaitEndOfRound(round uint32) <-chan struct{}
}

RoundClock is a timer interface.

type Set 

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

Set represents a unique set of values.

func NewDefaultEmptySet 

func NewDefaultEmptySet() *Set

NewDefaultEmptySet creates an empty set with the default size.

func NewEmptySet 

func NewEmptySet(size int) *Set

NewEmptySet creates an empty set with the provided size.

func NewSet 

func NewSet(data []types.ProposalID) *Set

NewSet creates a set from the provided array of values. Note: duplicated values are ignored.

func NewSetFromValues 

func NewSetFromValues(values ...types.ProposalID) *Set

NewSetFromValues creates a set of the provided values. Note: duplicated values are ignored.

func (*Set) Add 

func (s *Set) Add(id types.ProposalID)

Add a value to the set. It has no effect if the value already exists in the set.

func (*Set) Clone 

func (s *Set) Clone() *Set

Clone creates a copy of the set.

func (*Set) Complement 

func (s *Set) Complement(u *Set) *Set

Complement returns a new set that represents the complement of s relatively to the world u.

func (*Set) Contains 

func (s *Set) Contains(id types.ProposalID) bool

Contains returns true if the provided value is contained in the set, false otherwise.

func (*Set) Equals 

func (s *Set) Equals(g *Set) bool

Equals returns true if the provided set represents this set, false otherwise.

func (*Set) ID added in v0.1.11 

func (s *Set) ID() types.Hash32

ID returns the ObjectID of the set.

func (*Set) Intersection 

func (s *Set) Intersection(g *Set) *Set

Intersection returns the intersection a new set which represents the intersection of s and g.

func (*Set) IsSubSetOf 

func (s *Set) IsSubSetOf(g *Set) bool

IsSubSetOf returns true if s is a subset of g, false otherwise.

func (*Set) Remove 

func (s *Set) Remove(id types.ProposalID)

Remove a value from the set. It has no effect if the value doesn't exist in the set.

func (*Set) Size 

func (s *Set) Size() int

Size returns the number of SortedElements in the set.

func (*Set) String 

func (s *Set) String() string

func (*Set) Subtract 

func (s *Set) Subtract(g *Set)

Subtract g from s.

func (*Set) ToSlice 

func (s *Set) ToSlice() []types.ProposalID

ToSlice returns the array representation of the set.

func (*Set) Union 

func (s *Set) Union(g *Set) *Set

Union returns a new set which represents the union set of s and g.

type SimpleRoundClock added in v1.0.0 

type SimpleRoundClock struct {
	LayerTime     time.Time
	WakeupDelta   time.Duration
	RoundDuration time.Duration
}

SimpleRoundClock is a simple Hare-round clock. Repeated calls to AwaitEndOfRound() will each return a new channel and will be backed by a new timer which will not be garbage collected until it expires. To avoid leaking resources, callers should avoid calling AwaitEndOfRound() more than once for a given round (e.g. by storing the resulting channel and reusing it).

func NewSimpleRoundClock added in v1.0.0 

func NewSimpleRoundClock(layerTime time.Time, wakeupDelta, roundDuration time.Duration) *SimpleRoundClock

NewSimpleRoundClock returns a new SimpleRoundClock, given the provided configuration.

func (*SimpleRoundClock) AwaitEndOfRound added in v1.0.0 

func (c *SimpleRoundClock) AwaitEndOfRound(round uint32) <-chan struct{}

AwaitEndOfRound returns a channel that gets closed when the given round ends. Repeated calls to this method will return new instances of the channel and use new underlying timers which will not be garbage collected until they expire. To avoid leaking resources, callers should avoid calling AwaitEndOfRound() more than once for a given round (e.g. by storing the resulting channel and reusing it).

func (*SimpleRoundClock) AwaitWakeup added in v1.0.0 

func (c *SimpleRoundClock) AwaitWakeup() <-chan struct{}

AwaitWakeup returns a channel that gets closed when the Hare wakeup delay has passed.

func (*SimpleRoundClock) RoundEnd added in v1.0.0 

func (c *SimpleRoundClock) RoundEnd(round uint32) time.Time

RoundEnd returns the time at which round ends, passing round-1 will return the time at which round starts.

type State 

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

State holds the current state of the consensus process (aka the participant).

type TerminationOutput 

type TerminationOutput interface {
	ID() types.LayerID
	Set() *Set
	Coinflip() bool
	Completed() bool
}

TerminationOutput represents an output of a consensus process.

Source Files

View all Source files

Directories

Path Synopsis
Package eligibility is a generated GoMock package.
 Package eligibility is a generated GoMock package.
config
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

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.