qbft

package
v1.1.1 Latest Latest
Warning

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

 Go to latest Published: Feb 16, 2025 License: GPL-3.0 Imports: 11 Imported by: 1

README

QBFT

Introduction

This is a spec implementation for the QBFT protocol, following formal verification spec / github repo.

Important note on message processing

The spec only deals with message process logic but it's also very important the way controller.ProcessMsg is called. Message queueing and retry are important as there is no guarantee as to when a message is delivered. Examples:

  • A proposal message can be delivered after its respective prepare
  • A next round message can be delivered before the timer hits timeout
  • A late commit message can decide the instance even if it started the next round
  • A message can fail to process because it's "too early" or "too late"

Because of the above, there is a need to order and queue messages based on their round and type so to not lose message and make the protocol round change.

TODO

  • Support 4,7,10,13 committee sizes
  • Message encoding and validation spec tests
  • proposal/ prepare/ commit spec tests
  • round change spec tests
  • [//] Unified test suite, compatible with the formal verification spec
  • [//] Align according to spec and Roberto's comments
  • Remove round check from upon commit as it can be for any round?
  • Use data hashes instead of full data in msgs to save space in justifications

Documentation

Overview

Code generated by fastssz. DO NOT EDIT. Hash: 6732475e30a3885e05ad0c04dfd8b3ca58aae4ebd22fa32781bb39c9d2f307c2 Version: 0.1.3

Index

Constants

View Source 
const (
	NoRound     Round  = 0 // NoRound represents a nil/ zero round
	FirstRound  Round  = 1 // FirstRound value is the first round in any QBFT instance start
	FirstHeight Height = 0
)

Variables

View Source 
var (
	QuickTimeoutThreshold = Round(8)
	QuickTimeout          = 2 * time.Second
	SlowTimeout           = 2 * time.Minute
	// CutoffRound which round the instance should stop its timer and progress no further
	CutoffRound = 12 // stop processing attestations after 8*2+120*3 = 6.2 min (~ 1 epoch)
)

At the moment, these variables are useful for the node implementation TODO: It's usage should be updated in the PR https://github.com/ssvlabs/ssv-spec/pull/352

Functions

func ControllerIdToMessageID 

func ControllerIdToMessageID(identifier []byte) types.MessageID

func CreateCommit 

func CreateCommit(state *State, signer *types.OperatorSigner, root [32]byte) (*types.SignedSSVMessage, error)

CreateCommit * Commit( 

signCommit(
    UnsignedCommit(
        |current.blockchain|,
        current.round,
        signHash(hashBlockForCommitSeal(proposedBlock), current.id),
        digest(proposedBlock)),
        current.id
    )
);

func CreatePrepare 

func CreatePrepare(state *State, signer *types.OperatorSigner, newRound Round, root [32]byte) (*types.SignedSSVMessage, error)

CreatePrepare * Prepare( 

    signPrepare(
        UnsignedPrepare(
            |current.blockchain|,
            newRound,
            digest(m.proposedBlock)),
        current.id
        )
);

func CreateProposal 

func CreateProposal(state *State, signer *types.OperatorSigner, fullData []byte, roundChanges,
	prepares []*ProcessingMessage) (*types.SignedSSVMessage, error)

CreateProposal * 

	Proposal(
                      signProposal(
                          UnsignedProposal(
                              |current.blockchain|,
                              newRound,
                              digest(block)),
                          current.id),
                      block,
                      extractSignedRoundChanges(roundChanges),
                      extractSignedPrepares(prepares));

func CreateRoundChange 

func CreateRoundChange(state *State, signer *types.OperatorSigner, newRound Round, instanceStartValue []byte) (*types.SignedSSVMessage, error)

CreateRoundChange * RoundChange( 

    signRoundChange(
        UnsignedRoundChange(
            |current.blockchain|,
            newRound,
            digestOptionalBlock(current.lastPreparedBlock),
            current.lastPreparedRound),
    current.id),
    current.lastPreparedBlock,
    getRoundChangeJustification(current)
)

func HasPartialQuorum 

func HasPartialQuorum(share *types.CommitteeMember, msgs []*ProcessingMessage) bool

HasPartialQuorum returns true if a unique set of signers has partial quorum

func HasQuorum 

func HasQuorum(share *types.CommitteeMember, msgs []*ProcessingMessage) bool

HasQuorum returns true if a unique set of signers has quorum

func HashDataRoot 

func HashDataRoot(data []byte) ([32]byte, error)

HashDataRoot hashes input data to root

func IsDecidedMsg 

func IsDecidedMsg(committeeMember *types.CommitteeMember, msg *ProcessingMessage) (bool, error)

IsDecidedMsg returns true if signed commit has all quorum sigs

func MarshalJustifications 

func MarshalJustifications(msgs []*types.SignedSSVMessage) ([][]byte, error)

func RoundRobinProposer 

func RoundRobinProposer(state *State, round Round) types.OperatorID

RoundRobinProposer returns the proposer for the round. Each new height starts with the first proposer and increments by 1 with each following round. Each new height has a different first round proposer which is +1 from the previous height. First height starts with index 0

func Sign added in v1.0.0 

func Sign(msg *Message, operatorID types.OperatorID, operatorSigner *types.OperatorSigner) (*types.SignedSSVMessage, error)

func ValidateDecided 

func ValidateDecided(
	config IConfig,
	msg *ProcessingMessage,
	committeeMember *types.CommitteeMember,
) error

Types

type Config 

type Config struct {
	Domain      types.DomainType
	ValueCheckF ProposedValueCheckF
	ProposerF   ProposerF
	Network     Network
	Timer       Timer
	CutOffRound Round
}

func (*Config) GetCutOffRound added in v1.0.0 

func (c *Config) GetCutOffRound() Round

func (*Config) GetNetwork 

func (c *Config) GetNetwork() Network

GetNetwork returns a p2p Network instance

func (*Config) GetProposerF 

func (c *Config) GetProposerF() ProposerF

GetProposerF returns func used to calculate proposer

func (*Config) GetSignatureDomainType 

func (c *Config) GetSignatureDomainType() types.DomainType

GetSignatureDomainType returns the Domain type used for signatures

func (*Config) GetTimer 

func (c *Config) GetTimer() Timer

GetTimer returns round timer

func (*Config) GetValueCheckF 

func (c *Config) GetValueCheckF() ProposedValueCheckF

GetValueCheckF returns value check instance

type Controller 

type Controller struct {
	Identifier []byte
	Height     Height // incremental Height for InstanceContainer
	// StoredInstances stores the last HistoricalInstanceCapacity in an array for message processing purposes.
	StoredInstances InstanceContainer
	CommitteeMember *types.CommitteeMember
	OperatorSigner  *types.OperatorSigner `json:"-"`
	// contains filtered or unexported fields
}

Controller is a QBFT coordinator responsible for starting and following the entire life cycle of multiple QBFT InstanceContainer

func NewController 

func NewController(identifier []byte, committeeMember *types.CommitteeMember, config IConfig,
	signer *types.OperatorSigner) *Controller

func (*Controller) BaseMsgValidation 

func (c *Controller) BaseMsgValidation(msg *ProcessingMessage) error

BaseMsgValidation returns error if msg is invalid (base validation)

func (*Controller) Decode 

func (c *Controller) Decode(data []byte) error

func (*Controller) Encode 

func (c *Controller) Encode() ([]byte, error)

Controller

func (*Controller) GetConfig 

func (c *Controller) GetConfig() IConfig

func (*Controller) GetIdentifier 

func (c *Controller) GetIdentifier() []byte

GetIdentifier returns QBFT Identifier, used to identify messages

func (*Controller) GetRoot 

func (c *Controller) GetRoot() ([32]byte, error)

func (*Controller) InstanceForHeight 

func (c *Controller) InstanceForHeight(height Height) *Instance

func (*Controller) ProcessMsg 

func (c *Controller) ProcessMsg(signedMessage *types.SignedSSVMessage) (*types.SignedSSVMessage, error)

ProcessMsg processes a new msg, returns decided message or error

func (*Controller) StartNewInstance 

func (c *Controller) StartNewInstance(height Height, value []byte) error

StartNewInstance will start a new QBFT instance, if can't will return error

func (*Controller) UponDecided 

func (c *Controller) UponDecided(msg *ProcessingMessage) (*types.SignedSSVMessage, error)

UponDecided returns decided msg if decided, nil otherwise

func (*Controller) UponExistingInstanceMsg 

func (c *Controller) UponExistingInstanceMsg(msg *ProcessingMessage) (*types.SignedSSVMessage, error)

type Height 

type Height uint64

type IConfig 

type IConfig interface {
	// GetValueCheckF returns value check function
	GetValueCheckF() ProposedValueCheckF
	// GetProposerF returns func used to calculate proposer
	GetProposerF() ProposerF
	// GetNetwork returns a p2p Network instance
	GetNetwork() Network
	// GetTimer returns round timer
	GetTimer() Timer
	// GetCutOffRound returns the round that stops the instance
	GetCutOffRound() Round
}

type Instance 

type Instance struct {
	State *State

	StartValue []byte
	// contains filtered or unexported fields
}

Instance is a single QBFT instance that starts with a Start call (including a value). Every new msg the ProcessMsg function needs to be called

func NewInstance 

func NewInstance(
	config IConfig,
	committeeMember *types.CommitteeMember,
	identifier []byte,
	height Height,
	signer *types.OperatorSigner,
) *Instance

func (*Instance) BaseMsgValidation 

func (i *Instance) BaseMsgValidation(msg *ProcessingMessage) error

func (*Instance) Broadcast 

func (i *Instance) Broadcast(msg *types.SignedSSVMessage) error

func (*Instance) CanProcessMessages 

func (i *Instance) CanProcessMessages() bool

CanProcessMessages will return true if instance can process messages

func (*Instance) Decode 

func (i *Instance) Decode(data []byte) error

func (*Instance) Encode 

func (i *Instance) Encode() ([]byte, error)

Instance

func (*Instance) ForceStop 

func (i *Instance) ForceStop()

func (*Instance) GetConfig 

func (i *Instance) GetConfig() IConfig

GetConfig returns the instance config

func (*Instance) GetHeight 

func (i *Instance) GetHeight() Height

GetHeight interface implementation

func (*Instance) GetRoot 

func (i *Instance) GetRoot() ([32]byte, error)

func (*Instance) IsDecided 

func (i *Instance) IsDecided() (bool, []byte)

IsDecided interface implementation

func (*Instance) MarshalJSON 

func (i *Instance) MarshalJSON() ([]byte, error)

MarshalJSON is a custom JSON marshaller for Instance

func (*Instance) ProcessMsg 

func (i *Instance) ProcessMsg(msg *ProcessingMessage) (decided bool, decidedValue []byte, aggregatedCommit *types.SignedSSVMessage, err error)

ProcessMsg processes a new QBFT msg, returns non nil error on msg processing error

func (*Instance) Start 

func (i *Instance) Start(value []byte, height Height)

Start is an interface implementation

func (*Instance) UnmarshalJSON 

func (i *Instance) UnmarshalJSON(data []byte) error

UnmarshalJSON is a custom JSON unmarshaller for Instance

func (*Instance) UponCommit 

func (i *Instance) UponCommit(msg *ProcessingMessage, commitMsgContainer *MsgContainer) (bool, []byte, *types.SignedSSVMessage, error)

UponCommit returns true if a quorum of commit messages was received. Assumes commit message is valid!

func (*Instance) UponRoundTimeout 

func (i *Instance) UponRoundTimeout() error

type InstanceContainer 

type InstanceContainer []*Instance

func (InstanceContainer) FindInstance 

func (i InstanceContainer) FindInstance(height Height) *Instance

type Message 

type Message struct {
	MsgType    MessageType
	Height     Height // QBFT instance Height
	Round      Round  // QBFT round for which the msg is for
	Identifier []byte `ssz-max:"56"` // instance Identifier this msg belongs to

	Root                     [32]byte `ssz-size:"32"`
	DataRound                Round    // The last round that obtained a Prepare quorum
	RoundChangeJustification [][]byte `ssz-max:"13,51852"`
	PrepareJustification     [][]byte `ssz-max:"13,3700"`
}

func DecodeMessage added in v1.0.0 

func DecodeMessage(data []byte) (*Message, error)

Creates a Message object from bytes

func (*Message) Decode 

func (msg *Message) Decode(data []byte) error

Decode returns error if decoding failed

func (*Message) Encode 

func (msg *Message) Encode() ([]byte, error)

Encode returns a msg encoded bytes or error

func (*Message) GetPrepareJustifications 

func (msg *Message) GetPrepareJustifications() ([]*types.SignedSSVMessage, error)

func (*Message) GetRoot 

func (msg *Message) GetRoot() ([32]byte, error)

GetRoot returns the root used for signing and verification

func (*Message) GetRoundChangeJustifications 

func (msg *Message) GetRoundChangeJustifications() ([]*types.SignedSSVMessage, error)

func (*Message) GetTree 

func (m *Message) GetTree() (*ssz.Node, error)

GetTree ssz hashes the Message object

func (*Message) HashTreeRoot 

func (m *Message) HashTreeRoot() ([32]byte, error)

HashTreeRoot ssz hashes the Message object

func (*Message) HashTreeRootWith 

func (m *Message) HashTreeRootWith(hh ssz.HashWalker) (err error)

HashTreeRootWith ssz hashes the Message object with a hasher

func (*Message) MarshalSSZ 

func (m *Message) MarshalSSZ() ([]byte, error)

MarshalSSZ ssz marshals the Message object

func (*Message) MarshalSSZTo 

func (m *Message) MarshalSSZTo(buf []byte) (dst []byte, err error)

MarshalSSZTo ssz marshals the Message object to a target array

func (*Message) RoundChangePrepared 

func (msg *Message) RoundChangePrepared() bool

RoundChangePrepared returns true if message is a RoundChange and prepared

func (*Message) SizeSSZ 

func (m *Message) SizeSSZ() (size int)

SizeSSZ returns the ssz encoded size in bytes for the Message object

func (*Message) UnmarshalSSZ 

func (m *Message) UnmarshalSSZ(buf []byte) error

UnmarshalSSZ ssz unmarshals the Message object

func (*Message) Validate 

func (msg *Message) Validate() error

Validate returns error if msg validation doesn't pass. Msg validation checks the msg, it's variables for validity.

type MessageType 

type MessageType uint64
const (
	ProposalMsgType MessageType = iota
	PrepareMsgType
	CommitMsgType
	RoundChangeMsgType
)

type MsgContainer 

type MsgContainer struct {
	Msgs map[Round][]*ProcessingMessage
}

func NewMsgContainer 

func NewMsgContainer() *MsgContainer

func (*MsgContainer) AddFirstMsgForSignerAndRound 

func (c *MsgContainer) AddFirstMsgForSignerAndRound(msg *ProcessingMessage) (bool, error)

AddFirstMsgForSignerAndRound will add the first msg for each signer for a specific round, consequent msgs will not be added

func (*MsgContainer) AddMsg 

func (c *MsgContainer) AddMsg(msg *ProcessingMessage) error

AddMsg will add any message regardless of signers

func (*MsgContainer) AllMessages added in v1.0.0 

func (c *MsgContainer) AllMessages() []*ProcessingMessage

AllMessages returns all messages

func (*MsgContainer) Decode 

func (c *MsgContainer) Decode(data []byte) error

func (*MsgContainer) Encode 

func (c *MsgContainer) Encode() ([]byte, error)

MsgContainer

func (*MsgContainer) GetRoot added in v1.0.0 

func (c *MsgContainer) GetRoot() ([32]byte, error)

func (*MsgContainer) LongestUniqueSignersForRoundAndRoot 

func (c *MsgContainer) LongestUniqueSignersForRoundAndRoot(round Round, root [32]byte) ([]types.OperatorID, []*ProcessingMessage)

LongestUniqueSignersForRoundAndRoot returns the longest set of unique signers and msgs for a specific round and value

func (*MsgContainer) MessagesForRound 

func (c *MsgContainer) MessagesForRound(round Round) []*ProcessingMessage

MessagesForRound returns all msgs for Height and round, empty slice otherwise

func (*MsgContainer) MessagesForRoundAndRoot 

func (c *MsgContainer) MessagesForRoundAndRoot(round Round, root [32]byte) []*ProcessingMessage

MessagesForRoundAndRoot returns all msgs for round and value, empty slice otherwise

type Network 

type Network interface {
	p2p.Broadcaster
}

Network is the interface for networking across QBFT components

type ProcessingMessage added in v1.0.0 

type ProcessingMessage struct {
	SignedMessage *types.SignedSSVMessage
	QBFTMessage   *Message
}

ProcessingMessage stores the network-exchanged signed message and the decoded SignedMessage.SSVMessage.Data (qbft message) The signed message is used at the qbft level since it's used for qbft justifications

func NewProcessingMessage added in v1.0.0 

func NewProcessingMessage(signedMessage *types.SignedSSVMessage) (*ProcessingMessage, error)

NewProcessingMessage creates a ProcessingMessage with the decoded qbft message

func (*ProcessingMessage) Validate added in v1.0.0 

func (msg *ProcessingMessage) Validate() error

Validate checks the signed message and qbft message validation

type ProposedValueCheckF 

type ProposedValueCheckF func(data []byte) error

type ProposerF 

type ProposerF func(state *State, round Round) types.OperatorID

type Round 

type Round uint64

type State 

type State struct {
	CommitteeMember                 *types.CommitteeMember
	ID                              []byte // instance Identifier
	Round                           Round
	Height                          Height
	LastPreparedRound               Round
	LastPreparedValue               []byte
	ProposalAcceptedForCurrentRound *ProcessingMessage
	Decided                         bool
	DecidedValue                    []byte

	ProposeContainer     *MsgContainer
	PrepareContainer     *MsgContainer
	CommitContainer      *MsgContainer
	RoundChangeContainer *MsgContainer
}

func (*State) Decode 

func (s *State) Decode(data []byte) error

func (*State) Encode 

func (s *State) Encode() ([]byte, error)

func (*State) GetRoot 

func (s *State) GetRoot() ([32]byte, error)

type Timer 

type Timer interface {
	// TimeoutForRound will reset running timer if exists and will start a new timer for a specific round
	TimeoutForRound(round Round)
}

Timer is an interface for a round timer, calling the UponRoundTimeout when times out

Source Files

View all Source files

Directories

Path Synopsis
generate
tests
tests/commit
tests/controller/decided
tests/controller/futuremsg
tests/controller/latemsg
tests/controller/processmsg
tests/messages
tests/prepare
tests/proposal
tests/proposer
tests/roundchange
tests/startinstance
tests/timeout

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.