spec: Clearly document the ordering within VoteInfo and ExtendedVoteInfo

Feature Request

Summary

It would be useful if the spec for ABCI 2.0 documented the expected ordering of elements within fields VoteInfo and ExtendedVoteInfo in all the methods where these fields appear. Application developers might expects that these elements are ordered deterministically by validator power; if so, the docs should capture it, and if not, we should also state it.

Problem Definition

Developers who are integrating v0.38 can be confused about the guarantees on the ordering of elements within VoteInfo and ExtendedVoteInfo. There are three ABCI methods concerned here:

Proposal

The method ValidatorSet.Validators already handles ordering:

cometbft/types/validator_set.go

Lines 38 to 53 in 2a0c1e6

    
           // ValidatorSet represent a set of *Validator at a given height. 
        
           // 
        
           // The validators can be fetched by address or index. 
        
           // The index is in order of .VotingPower, so the indices are fixed for all 
        
           // rounds of a given blockchain height - ie. the validators are sorted by their 
        
           // voting power (descending). Secondary index - .Address (ascending). 
        
           // 
        
           // On the other hand, the .ProposerPriority of each validator and the 
        
           // designated .GetProposer() of a set changes every round, upon calling 
        
           // .IncrementProposerPriority(). 
        
           // 
        
           // NOTE: Not goroutine-safe. 
        
           // NOTE: All get/set to validators should copy the value for safety. 
        
           type ValidatorSet struct { 
        
           	// NOTE: persisted via reflect, must be exported. 
        
           	Validators []*Validator `json:"validators"`

This method is used by buildExtendedCommitInfo and buildLastCommitInfo, used in the three ABCI methods described above.

Acceptance criteria:

double-check that the above is accurate
extend the specification for the three ABCI methods concerned to document the ordering guarantees

H/t Marko B. for noticing this underspecified part of the spec!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Feature Request

Summary

Problem Definition

Proposal

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	// ValidatorSet represent a set of *Validator at a given height.
	//
	// The validators can be fetched by address or index.
	// The index is in order of .VotingPower, so the indices are fixed for all
	// rounds of a given blockchain height - ie. the validators are sorted by their
	// voting power (descending). Secondary index - .Address (ascending).
	//
	// On the other hand, the .ProposerPriority of each validator and the
	// designated .GetProposer() of a set changes every round, upon calling
	// .IncrementProposerPriority().
	//
	// NOTE: Not goroutine-safe.
	// NOTE: All get/set to validators should copy the value for safety.
	type ValidatorSet struct {
	// NOTE: persisted via reflect, must be exported.
	Validators []*Validator `json:"validators"`

Description

Feature Request

Summary

Problem Definition

Proposal

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions