grandpa

package
v0.0.0-...-c69f244 Latest Latest
Warning

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

Go to latest
Published: Jul 16, 2022 License: LGPL-3.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNilBlockState    = errors.New("cannot have nil BlockState")
	ErrNilGrandpaState  = errors.New("cannot have nil GrandpaState")
	ErrNilDigestHandler = errors.New("cannot have nil DigestHandler")
	ErrNilKeypair       = errors.New("cannot have nil keypair")
	ErrNilNetwork       = errors.New("cannot have nil Network")

	// ErrBlockDoesNotExist is returned when trying to validate a vote for a block that doesn't exist
	ErrBlockDoesNotExist = errors.New("block does not exist")

	// ErrInvalidSignature is returned when trying to validate a vote message with an invalid signature
	ErrInvalidSignature = errors.New("signature is not valid")

	// ErrSetIDMismatch is returned when trying to validate a vote message
	// with an invalid voter set ID, or when receiving a catch up message
	// with a different set ID
	ErrSetIDMismatch = errors.New("set IDs do not match")

	// ErrEquivocation is returned when trying to validate a vote for that is equivocatory
	ErrEquivocation = errors.New("vote is equivocatory")

	// ErrVoterNotFound is returned when trying to validate a vote for a voter that isn't in the voter set
	ErrVoterNotFound = errors.New("voter is not in voter set")

	// ErrDescendantNotFound is returned when trying to validate a vote
	// for a block that isn't a descendant of the last finalised block
	ErrDescendantNotFound = blocktree.ErrDescendantNotFound

	// ErrNoPreVotedBlock is returned when there is no pre-voted block for a round.
	// this can only happen in the case of > 1/3 byzantine nodes (ie > 1/3 nodes equivocate or don't submit valid votes)
	ErrNoPreVotedBlock = errors.New("cannot get pre-voted block")

	// ErrNoGHOST is returned when there is no GHOST. the only case where this could happen is if there are no votes
	// at all, so it shouldn't ever happen.
	ErrNoGHOST = errors.New("cannot determine grandpa-GHOST")

	// ErrCannotDecodeSubround is returned when a subround value cannot be decoded
	ErrCannotDecodeSubround = errors.New("cannot decode invalid subround value")

	// ErrInvalidMessageType is returned when a network.Message cannot be decoded
	ErrInvalidMessageType = errors.New("cannot decode invalid message type")

	// ErrNotCommitMessage is returned when calling GetFinalisedHash on a message that isn't a CommitMessage
	ErrNotCommitMessage = errors.New("cannot get finalised hash from VoteMessage")

	// ErrNoJustification is returned when no justification can be found for a block, ie. it has not been finalised
	ErrNoJustification = errors.New("no justification found for block")

	ErrBlockHashMismatch = errors.New("block hash does not correspond to given block number")

	// ErrMinVotesNotMet is returned when the number of votes is less than the required minimum in a Justification
	ErrMinVotesNotMet = errors.New("minimum number of votes not met in a Justification")

	// ErrInvalidCatchUpRound is returned when a catch-up message is received with an invalid round
	ErrInvalidCatchUpRound = errors.New("catch up request is for future round")

	// ErrInvalidCatchUpResponseRound is returned when a catch-up response is received with an invalid round
	ErrInvalidCatchUpResponseRound = errors.New("catch up response is not for previous round")

	// ErrGHOSTlessCatchUp is returned when a catch up response
	// does not contain a valid grandpa-GHOST (ie. finalised block)
	ErrGHOSTlessCatchUp = errors.New("catch up response does not contain grandpa-GHOST")

	// ErrCatchUpResponseNotCompletable is returned when the round represented by the catch up response is not completable
	ErrCatchUpResponseNotCompletable = errors.New("catch up response is not completable")

	// ErrServicePaused is returned if the service is paused and waiting for catch up messages
	ErrServicePaused = errors.New("service is paused")

	// ErrPrecommitSignatureMismatch is returned when the number of precommits
	// and signatures in a CommitMessage do not match
	ErrPrecommitSignatureMismatch = errors.New("number of precommits does not match number of signatures")

	// ErrPrecommitBlockMismatch is returned when a precommit hash within a
	// justification is not a descendant of the committed block
	ErrPrecommitBlockMismatch = errors.New("precommit block is not descendant of committed block")

	// ErrAuthorityNotInSet is returned when a precommit within a justification is signed by a key not in the authority set
	ErrAuthorityNotInSet = errors.New("authority is not in set")
)
View Source
var (
	ErrUnsupportedSubround = errors.New("unsupported subround")
)

Functions

This section is empty.

Types

type AuthData

type AuthData struct {
	Signature   [64]byte
	AuthorityID ed25519.PublicKeyBytes
}

AuthData represents signature data within a CommitMessage to be paired with a precommit

type BlockState

type BlockState interface {
	GenesisHash() common.Hash
	HasHeader(hash common.Hash) (bool, error)
	GetHeader(hash common.Hash) (*types.Header, error)
	GetHeaderByNumber(num uint) (*types.Header, error)
	IsDescendantOf(parent, child common.Hash) (bool, error)
	HighestCommonAncestor(a, b common.Hash) (common.Hash, error)
	HasFinalisedBlock(round, setID uint64) (bool, error)
	GetFinalisedHeader(uint64, uint64) (*types.Header, error)
	SetFinalisedHash(common.Hash, uint64, uint64) error
	BestBlockHeader() (*types.Header, error)
	BestBlockHash() common.Hash
	Leaves() []common.Hash
	GetHighestFinalisedHeader() (*types.Header, error)
	BlocktreeAsString() string
	GetImportedBlockNotifierChannel() chan *types.Block
	FreeImportedBlockNotifierChannel(ch chan *types.Block)
	GetFinalisedNotifierChannel() chan *types.FinalisationInfo
	FreeFinalisedNotifierChannel(ch chan *types.FinalisationInfo)
	SetJustification(hash common.Hash, data []byte) error
	HasJustification(hash common.Hash) (bool, error)
	GetJustification(hash common.Hash) ([]byte, error)
	GetHashByNumber(num uint) (common.Hash, error)
	BestBlockNumber() (blockNumber uint, err error)
	GetHighestRoundAndSetID() (uint64, uint64, error)
}

BlockState is the interface required by GRANDPA into the block state

type CatchUpRequest

type CatchUpRequest struct {
	Round uint64
	SetID uint64
}

CatchUpRequest struct to represent a CatchUpRequest message

func (CatchUpRequest) Index

func (r CatchUpRequest) Index() uint

Index Returns VDT index

func (*CatchUpRequest) ToConsensusMessage

func (r *CatchUpRequest) ToConsensusMessage() (*ConsensusMessage, error)

ToConsensusMessage converts the catchUpRequest into a network-level consensus message

type CatchUpResponse

type CatchUpResponse struct {
	SetID                  uint64
	Round                  uint64
	PreVoteJustification   []SignedVote
	PreCommitJustification []SignedVote
	Hash                   common.Hash
	Number                 uint32
}

CatchUpResponse struct to represent a CatchUpResponse message

func (CatchUpResponse) Index

func (r CatchUpResponse) Index() uint

Index Returns VDT index

func (*CatchUpResponse) ToConsensusMessage

func (r *CatchUpResponse) ToConsensusMessage() (*ConsensusMessage, error)

ToConsensusMessage converts the catchUpResponse into a network-level consensus message

type Commit

type Commit struct {
	Hash       common.Hash
	Number     uint32
	Precommits []SignedVote
}

Commit contains all the signed precommits for a given block

type CommitMessage

type CommitMessage struct {
	Round      uint64
	SetID      uint64
	Vote       Vote
	Precommits []Vote
	AuthData   []AuthData
}

CommitMessage represents a network finalisation message

func (CommitMessage) Index

func (f CommitMessage) Index() uint

Index Returns VDT index

func (*CommitMessage) ToConsensusMessage

func (f *CommitMessage) ToConsensusMessage() (*ConsensusMessage, error)

ToConsensusMessage converts the CommitMessage into a network-level consensus message

type Config

type Config struct {
	LogLvl        log.Level
	BlockState    BlockState
	GrandpaState  GrandpaState
	DigestHandler DigestHandler
	Network       Network
	Voters        []Voter
	Keypair       *ed25519.Keypair
	Authority     bool
	Interval      time.Duration
	Telemetry     telemetry.Client
}

Config represents a GRANDPA service configuration

type ConsensusMessage

type ConsensusMessage = network.ConsensusMessage

ConsensusMessage is an alias for network.ConsensusMessage

type DigestHandler

type DigestHandler interface {
	NextGrandpaAuthorityChange() uint
}

DigestHandler is the interface required by GRANDPA for the digest handler

type FullVote

type FullVote struct {
	Stage Subround
	Vote  Vote
	Round uint64
	SetID uint64
}

FullVote represents a vote with additional information about the state this is encoded and signed and the signature is included in SignedMessage

type GrandpaHandshake

type GrandpaHandshake struct {
	Roles byte
}

GrandpaHandshake is exchanged by nodes that are beginning the grandpa protocol

func (*GrandpaHandshake) Decode

func (hs *GrandpaHandshake) Decode(in []byte) error

Decode the message into a GrandpaHandshake

func (*GrandpaHandshake) Encode

func (hs *GrandpaHandshake) Encode() ([]byte, error)

Encode encodes a GrandpaHandshake message using SCALE

func (*GrandpaHandshake) Hash

func (*GrandpaHandshake) Hash() (common.Hash, error)

Hash ...

func (*GrandpaHandshake) IsHandshake

func (*GrandpaHandshake) IsHandshake() bool

IsHandshake returns true

func (*GrandpaHandshake) String

func (hs *GrandpaHandshake) String() string

String formats a BlockAnnounceHandshake as a string

func (*GrandpaHandshake) SubProtocol

func (*GrandpaHandshake) SubProtocol() string

SubProtocol returns the grandpa sub-protocol

func (*GrandpaHandshake) Type

func (*GrandpaHandshake) Type() byte

Type ...

type GrandpaMessage

type GrandpaMessage interface {
	ToConsensusMessage() (*network.ConsensusMessage, error)
}

GrandpaMessage is implemented by all GRANDPA network messages

type GrandpaState

type GrandpaState interface {
	GetCurrentSetID() (uint64, error)
	GetAuthorities(setID uint64) ([]types.GrandpaVoter, error)
	GetSetIDByBlockNumber(num uint) (uint64, error)
	SetLatestRound(round uint64) error
	GetLatestRound() (uint64, error)
	SetPrevotes(round, setID uint64, data []SignedVote) error
	SetPrecommits(round, setID uint64, data []SignedVote) error
	GetPrevotes(round, setID uint64) ([]SignedVote, error)
	GetPrecommits(round, setID uint64) ([]SignedVote, error)
}

GrandpaState is the interface required by grandpa into the grandpa state

type Handshake

type Handshake = network.Handshake

Handshake is an alias for network.Handshake

type Justification

type Justification struct {
	Round  uint64
	Commit Commit
}

Justification represents a finality justification for a block

type Message

type Message = network.Message

Message is an alias for network.Message

type MessageHandler

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

MessageHandler handles GRANDPA consensus messages

func NewMessageHandler

func NewMessageHandler(grandpa *Service, blockState BlockState, telemetryMailer telemetry.Client) *MessageHandler

NewMessageHandler returns a new MessageHandler

type NeighbourMessage

type NeighbourMessage struct {
	Version byte
	Round   uint64
	SetID   uint64
	Number  uint32
}

NeighbourMessage represents a network-level neighbour message

func (NeighbourMessage) Index

func (m NeighbourMessage) Index() uint

Index Returns VDT index

func (*NeighbourMessage) ToConsensusMessage

func (m *NeighbourMessage) ToConsensusMessage() (*network.ConsensusMessage, error)

ToConsensusMessage converts the NeighbourMessage into a network-level consensus message

type Network

type Network interface {
	GossipMessage(msg network.NotificationsMessage)
	SendMessage(to peer.ID, msg NotificationsMessage) error
	RegisterNotificationsProtocol(sub protocol.ID,
		messageID byte,
		handshakeGetter network.HandshakeGetter,
		handshakeDecoder network.HandshakeDecoder,
		handshakeValidator network.HandshakeValidator,
		messageDecoder network.MessageDecoder,
		messageHandler network.NotificationsMessageHandler,
		batchHandler network.NotificationsMessageBatchHandler,
	) error
}

Network is the interface required by GRANDPA for the network

type NotificationsMessage

type NotificationsMessage = network.NotificationsMessage

NotificationsMessage is an alias for network.NotificationsMessage

type Service

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

Service represents the current state of the grandpa protocol

func NewService

func NewService(cfg *Config) (*Service, error)

NewService returns a new GRANDPA Service instance.

func (*Service) GetRound

func (s *Service) GetRound() uint64

GetRound return the current round number

func (*Service) GetSetID

func (s *Service) GetSetID() uint64

GetSetID returns the current setID

func (*Service) GetVoters

func (s *Service) GetVoters() Voters

GetVoters returns the list of current grandpa.Voters

func (*Service) PreCommits

func (s *Service) PreCommits() []ed25519.PublicKeyBytes

PreCommits returns the current precommits to the current round

func (*Service) PreVotes

func (s *Service) PreVotes() []ed25519.PublicKeyBytes

PreVotes returns the current prevotes to the current round

func (*Service) Start

func (s *Service) Start() error

Start begins the GRANDPA finality service

func (*Service) Stop

func (s *Service) Stop() error

Stop stops the GRANDPA finality service

func (*Service) VerifyBlockJustification

func (s *Service) VerifyBlockJustification(hash common.Hash, justification []byte) error

VerifyBlockJustification verifies the finality justification for a block

type SignedMessage

type SignedMessage struct {
	Stage       Subround // 0 for pre-vote, 1 for pre-commit, 2 for primary proposal
	BlockHash   common.Hash
	Number      uint32
	Signature   [64]byte // ed25519.SignatureLength
	AuthorityID ed25519.PublicKeyBytes
}

SignedMessage represents a block hash and number signed by an authority

func (SignedMessage) String

func (m SignedMessage) String() string

String returns the SignedMessage as a string

type SignedVote

type SignedVote = types.GrandpaSignedVote

type State

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

State represents a GRANDPA state

func NewState

func NewState(voters []Voter, setID, round uint64) *State

NewState returns a new GRANDPA state

type Subround

type Subround byte

Subround subrounds in a grandpa round

func (Subround) String

func (s Subround) String() string

type Vote

type Vote = types.GrandpaVote

func NewVote

func NewVote(hash common.Hash, number uint32) *Vote

NewVote returns a new Vote given a block hash and number

func NewVoteFromHash

func NewVoteFromHash(hash common.Hash, blockState BlockState) (*Vote, error)

NewVoteFromHash returns a new Vote given a hash and a blockState

func NewVoteFromHeader

func NewVoteFromHeader(h *types.Header) *Vote

NewVoteFromHeader returns a new Vote for a given header

type VoteMessage

type VoteMessage struct {
	Round   uint64
	SetID   uint64
	Message SignedMessage
}

VoteMessage represents a network-level vote message https://github.com/paritytech/substrate/blob/master/client/finality-grandpa/src/communication/gossip.rs#L336

func (VoteMessage) Index

func (v VoteMessage) Index() uint

Index Returns VDT index

func (*VoteMessage) ToConsensusMessage

func (v *VoteMessage) ToConsensusMessage() (*ConsensusMessage, error)

ToConsensusMessage converts the VoteMessage into a network-level consensus message

type Voter

type Voter = types.GrandpaVoter

type Voters

type Voters = types.GrandpaVoters

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL