hare

Documentation

Overview

Package hare implements the Hare Protocol.

Index

• Constants
• Variables
• type Broker
  • func (b *Broker) Register(id instanceID) (chan *Msg, error)
  • func (b *Broker) Start() error
  • func (b *Broker) Synced(id instanceID) bool
  • func (b *Broker) Unregister(id instanceID)
• type Closer
  • func NewCloser() Closer
  • func (closer *Closer) Close()
  • func (closer *Closer) CloseChannel() chan struct{}
• type Consensus
• type Hare
  • func New(conf config.Config, p2p NetworkService, sign Signer, nid types.NodeID, ...) *Hare
  • func (h *Hare) GetResult(lid types.LayerID) ([]types.BlockID, error)
  • func (h *Hare) Start() error
• type Message
  • func MessageFromBuffer(buffer []byte) (*Message, error)
  • func (m *Message) String() string
• type Msg
  • func (m *Msg) Bytes() []byte
  • func (m *Msg) String() string
• type NetworkService
• type RefCountTracker
  • func NewRefCountTracker() *RefCountTracker
  • func (tracker *RefCountTracker) CountStatus(id interface{}) uint32
  • func (tracker *RefCountTracker) Track(id interface{})
• type Rolacle
• type Set
  • func NewDefaultEmptySet() *Set
  • func NewEmptySet(size int) *Set
  • func NewSet(data []types.BlockID) *Set
  • func NewSetFromValues(values ...types.BlockID) *Set
  • func (s *Set) Add(id types.BlockID)
  • func (s *Set) Clone() *Set
  • func (s *Set) Complement(u *Set) *Set
  • func (s *Set) Contains(id types.BlockID) bool
  • func (s *Set) Equals(g *Set) bool
  • func (s *Set) ID() uint32
  • func (s *Set) Intersection(g *Set) *Set
  • func (s *Set) IsSubSetOf(g *Set) bool
  • func (s *Set) Remove(id types.BlockID)
  • func (s *Set) Size() int
  • func (s *Set) String() string
  • func (s *Set) Subtract(g *Set)
  • func (s *Set) ToSlice() []types.BlockID
  • func (s *Set) Union(g *Set) *Set
• type Signer
• type State
• type StateQuerier
• type TerminationOutput

Constants

const LayerBuffer = 20

LayerBuffer is the number of layer results we keep at a given time.

Variables

var ErrTooLate = errors.New("consensus process %v finished too late")

ErrTooLate means that the consensus was terminated too late

var (
	// ErrTooOld means the requested result has already been evacuated from the buffer because the layer is too old
	ErrTooOld = errors.New("layer has already been evacuated from buffer")
)

Types

type Broker

type Broker struct {
	Closer
	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) Register

func (b *Broker) Register(id instanceID) (chan *Msg, 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() error

Start listening to Hare messages (non-blocking).

func (*Broker) Synced

func (b *Broker) Synced(id instanceID) bool

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

func (*Broker) Unregister

func (b *Broker) Unregister(id instanceID)

Unregister a layer from receiving messages

type Closer

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

Closer adds the ability to close objects.

func NewCloser

func NewCloser() Closer

NewCloser creates a new (not closed) closer.

func (*Closer) Close

func (closer *Closer) Close()

Close signals all listening instances to close. Note: should be called only once.

func (*Closer) CloseChannel

func (closer *Closer) CloseChannel() chan struct{}

CloseChannel returns the channel to wait on for close signal.

type Consensus

type Consensus interface {
	ID() instanceID
	Close()
	CloseChannel() chan struct{}

	Start() error
	SetInbox(chan *Msg)
}

Consensus represents an item that acts like a consensus process.

type Hare

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

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

func New

func New(conf config.Config, p2p NetworkService, sign Signer, nid types.NodeID, validate outputValidationFunc,
	syncState syncStateFunc, obp layers, rolacle Rolacle,
	layersPerEpoch uint16, idProvider identityProvider, stateQ StateQuerier,
	beginLayer chan types.LayerID, logger log.Log) *Hare

New returns a new Hare struct.

func (*Hare) GetResult

func (h *Hare) GetResult(lid types.LayerID) ([]types.BlockID, error)

GetResult returns the hare output for the provided range. Returns error iff the request for the upper is too old.

func (*Hare) Start

func (h *Hare) Start() error

Start starts listening for layers and outputs.

type Message

type Message struct {
	Sig      []byte
	InnerMsg *innerMessage
}

Message is the tuple of a message and its corresponding signature.

func MessageFromBuffer

func MessageFromBuffer(buffer []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) String

func (m *Message) String() string

type Msg

type Msg struct {
	*Message
	PubKey *signing.PublicKey
}

Msg is the wrapper of the protocol's message. Messages are sent as type Message. Upon receiving, the public key 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.

func (*Msg) String

func (m *Msg) String() string

type NetworkService

type NetworkService interface {
	RegisterGossipProtocol(protocol string, prio priorityq.Priority) chan service.GossipMessage
	Broadcast(protocol string, payload []byte) error
}

NetworkService provides the registration and broadcast abilities in the network.

type RefCountTracker

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

RefCountTracker tracks the number of references of any object id.

func NewRefCountTracker

func NewRefCountTracker() *RefCountTracker

NewRefCountTracker creates a new reference count tracker.

func (*RefCountTracker) CountStatus

func (tracker *RefCountTracker) CountStatus(id interface{}) uint32

CountStatus returns the number of references to the given id.

func (*RefCountTracker) Track

func (tracker *RefCountTracker) Track(id interface{})

Track increases the count for the given object id.

type Rolacle

type Rolacle interface {
	Eligible(layer types.LayerID, round int32, committeeSize int, id types.NodeID, sig []byte) (bool, error)
	Proof(layer types.LayerID, round int32) ([]byte, error)
	IsIdentityActiveOnConsensusView(edID string, layer types.LayerID) (bool, error)
}

Rolacle is the roles oracle provider.

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.BlockID) *Set

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

func NewSetFromValues

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

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

func (*Set) Add

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

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.BlockID) 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

func (s *Set) ID() uint32

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.BlockID)

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 elements 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.BlockID

ToSlice returns the array representation of the set.

func (*Set) Union

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

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

type Signer

type Signer interface {
	Sign(m []byte) []byte
	PublicKey() *signing.PublicKey
}

Signer provides signing and public-key getter.

type State

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

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

type StateQuerier

type StateQuerier interface {
	IsIdentityActiveOnConsensusView(edID string, layer types.LayerID) (bool, error)
}

StateQuerier provides a query to check if an Ed public key is active on the current consensus view. It returns true if the identity is active and false otherwise. An error is set iff the identity could not be checked for activeness.

type TerminationOutput

type TerminationOutput interface {
	ID() instanceID
	Set() *Set
	Completed() bool
}

TerminationOutput represents an output of a consensus process.