grandpa

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Mar 1, 2024 License: LGPL-3.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// 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")
	ErrJustificationMismatch = errors.New("justification does not correspond to given block hash")

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

	ErrBlockNumbersMismatch = errors.New("block numbers mismatch")

	// 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")

	// 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 (
	ErrNeighbourVersionNotSupported = errors.New("neighbour version not supported")
)
View Source
var (
	ErrUnsupportedSubround = errors.New("unsupported subround")
)

Functions

This section is empty.

Types

type AuthData added in v0.7.0

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

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

func (*AuthData) String added in v0.8.0

func (a *AuthData) String() string

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)
	LowestCommonAncestor(a, b common.Hash) (common.Hash, error)
	HasFinalisedBlock(round, setID uint64) (bool, error)
	GetFinalisedHeader(round, setID uint64) (*types.Header, error)
	GetFinalisedHash(round, setID uint64) (common.Hash, error)
	SetFinalisedHash(common.Hash, uint64, uint64) error
	BestBlockHeader() (*types.Header, error)
	GetHighestFinalisedHeader() (*types.Header, error)
	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
	BestBlockNumber() (blockNumber uint, err error)
	GetHighestRoundAndSetID() (uint64, uint64, error)
	BestBlockHash() common.Hash
	GetRuntime(blockHash common.Hash) (instance runtime.Instance, err error)
}

BlockState is the interface required by GRANDPA into the block state

type CatchUpRequest added in v0.7.0

type CatchUpRequest struct {
	Round uint64
	SetID uint64
}

CatchUpRequest struct to represent a CatchUpRequest message

func (CatchUpRequest) String added in v0.8.0

func (r CatchUpRequest) String() string

func (*CatchUpRequest) ToConsensusMessage added in v0.7.0

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

ToConsensusMessage converts the catchUpRequest into a network-level consensus message

type CatchUpResponse added in v0.7.0

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) String added in v0.8.0

func (r CatchUpResponse) String() string

func (*CatchUpResponse) ToConsensusMessage added in v0.7.0

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

ToConsensusMessage converts the catchUpResponse into a network-level consensus message

type Commit added in v0.7.0

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

Commit contains all the signed precommits for a given block

type CommitMessage added in v0.7.0

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

CommitMessage represents a network finalisation message

func (CommitMessage) String added in v0.8.0

func (m CommitMessage) String() string

func (*CommitMessage) ToConsensusMessage added in v0.7.0

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

ToConsensusMessage converts the CommitMessage into a network-level consensus message

type Config added in v0.2.0

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

Config represents a GRANDPA service configuration

type ConsensusMessage added in v0.2.0

type ConsensusMessage = network.ConsensusMessage

ConsensusMessage is an alias for network.ConsensusMessage

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 added in v0.3.0

type GrandpaHandshake struct {
	Role common.NetworkRole
}

GrandpaHandshake is exchanged by nodes that are beginning the grandpa protocol

func (*GrandpaHandshake) Decode added in v0.3.0

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

Decode the message into a GrandpaHandshake

func (*GrandpaHandshake) Encode added in v0.3.0

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

Encode encodes a GrandpaHandshake message using SCALE

func (*GrandpaHandshake) IsValid added in v0.7.0

func (hs *GrandpaHandshake) IsValid() bool

IsValid return if it is a valid handshake.

func (*GrandpaHandshake) String added in v0.3.0

func (hs *GrandpaHandshake) String() string

String formats a BlockAnnounceHandshake as a string

type GrandpaMessage added in v0.3.0

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

GrandpaMessage is implemented by all GRANDPA network messages

type GrandpaState added in v0.7.0

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)
	NextGrandpaAuthorityChange(bestBlockHash common.Hash, bestBlockNumber uint) (blockHeight uint, err error)
}

GrandpaState is the interface required by grandpa into the grandpa state

type Justification

type Justification struct {
	Round  uint64
	Commit Commit
}

Justification represents a finality justification for a block

type MessageHandler added in v0.2.0

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

MessageHandler handles GRANDPA consensus messages

func NewMessageHandler added in v0.2.0

func NewMessageHandler(grandpa *Service, blockState BlockState, telemetryMailer Telemetry) *MessageHandler

NewMessageHandler returns a new MessageHandler

type NeighbourPacketV1 added in v0.7.0

type NeighbourPacketV1 struct {
	Round  uint64
	SetID  uint64
	Number uint32
}

NeighbourPacketV1 represents a network-level neighbour message currently, round and setID represents a struct containing an u64 https://github.com/paritytech/substrate/blob/master/client/finality-grandpa/src/communication/mod.rs#L660

func (NeighbourPacketV1) String added in v0.8.0

func (m NeighbourPacketV1) String() string

func (*NeighbourPacketV1) ToConsensusMessage added in v0.7.0

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

ToConsensusMessage converts the NeighbourMessage into a network-level consensus message

type Network added in v0.3.0

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

Network is the interface required by GRANDPA for the network

type NotificationsMessage added in v0.3.0

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 added in v0.7.0

func (s *Service) GetRound() uint64

GetRound return the current round number

func (*Service) GetSetID added in v0.7.0

func (s *Service) GetSetID() uint64

GetSetID returns the current setID

func (*Service) GetVoters added in v0.7.0

func (s *Service) GetVoters() Voters

GetVoters returns the list of current grandpa.Voters

func (*Service) PreCommits added in v0.7.0

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

PreCommits returns the current precommits to the current round

func (*Service) PreVotes added in v0.7.0

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

PreVotes returns the current prevotes to the current round

func (*Service) Start added in v0.2.0

func (s *Service) Start() error

Start begins the GRANDPA finality service

func (*Service) Stop added in v0.2.0

func (s *Service) Stop() error

Stop stops the GRANDPA finality service

func (*Service) VerifyBlockJustification added in v0.7.0

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

VerifyBlockJustification verifies the finality justification for a block, returns scale encoded justification with any extra bytes removed.

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 added in v0.2.0

func (m SignedMessage) String() string

String returns the SignedMessage as a string

type SignedVote added in v0.7.0

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 added in v0.7.0

type Subround byte

Subround subrounds in a grandpa round

func (Subround) String added in v0.7.0

func (s Subround) String() string

type Telemetry added in v0.8.0

type Telemetry interface {
	SendMessage(msg json.Marshaler)
}

Telemetry is the telemetry client to send telemetry messages.

type VersionedNeighbourPacket added in v0.7.0

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

func (VersionedNeighbourPacket) IndexValue added in v0.9.0

func (mvdt VersionedNeighbourPacket) IndexValue() (index uint, value any, err error)

func (*VersionedNeighbourPacket) SetValue added in v0.9.0

func (mvdt *VersionedNeighbourPacket) SetValue(value any) (err error)

func (VersionedNeighbourPacket) Value added in v0.7.0

func (mvdt VersionedNeighbourPacket) Value() (value any, err error)

func (VersionedNeighbourPacket) ValueAt added in v0.9.0

func (mvdt VersionedNeighbourPacket) ValueAt(index uint) (value any, err error)

type VersionedNeighbourPacketValues added in v0.9.0

type VersionedNeighbourPacketValues interface {
	NeighbourPacketV1
}

VersionedNeighbourPacket represents the enum of neighbour messages

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) String added in v0.7.0

func (v VoteMessage) String() string

func (*VoteMessage) ToConsensusMessage added in v0.2.0

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

ToConsensusMessage converts the VoteMessage into a network-level consensus message

type Voter

type Voter = types.GrandpaVoter

type Voters added in v0.2.0

type Voters = types.GrandpaVoters

Jump to

Keyboard shortcuts

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