Validator Signing

Here we specify the rules for validating a proposal and vote before signing. When a validator signs each message, and what it signs, is specified by the consensus protocol. First we include some general notes on validating data structures common to both types. We then provide specific validation rules for each. Finally, we include validation rules to prevent double-signing.

SignedMsgType

The SignedMsgType is a single byte that refers to the type of the message being signed. It is defined in Go as follows:

// SignedMsgType is a type of signed message in the consensus.
type SignedMsgType byte

const (
 // Votes
 PrevoteType   SignedMsgType = 0x01
 PrecommitType SignedMsgType = 0x02

 // Proposals
 ProposalType SignedMsgType = 0x20

 // Proposer liveness, from CONSENSUS_VERSION_2
 ProposerHeartbeatType SignedMsgType = 0x30
 RoundSkipType         SignedMsgType = 0x31
)

All signed messages must correspond to one of these types.

Timestamp

Votes carry no timestamp. A proposal's Timestamp must equal the proposed block's Header.Time, which the proposer takes from its local clock (the genesis time for the initial block). Fresh proposals must be timely with respect to their receive time and the chain's SynchronyParams before a validator prevotes their block. The timeliness check is skipped for a locally recorded valid block and during replay. The rules are specified in Proposal timestamps and time rules and the prevote decision in Transitions and decision rules.

ChainID

ChainID is an unstructured string with a max length of 50-bytes. In the future, the ChainID may become structured, and may take on longer lengths. For now, it is recommended that signers be configured for a particular ChainID, and to only sign votes and proposals corresponding to that ChainID.

BlockID

BlockID contains the block-header hash, PartSetHeader (part count and Merkle root of serialized block parts), and the state-ID hash. A nil vote has all three empty. A complete ID has 32-byte block, part-set and state hashes and a positive part count. Proposals require a complete ID; votes allow nil or complete IDs. See BlockID and the StateID schema below.

Proposals

The structure of a proposal for signing looks like:

type CanonicalProposal struct {
 Type      SignedMsgType // type alias for byte
 Height    int64         `binary:"fixed64"`
 Round     int64         `binary:"fixed64"`
 POLRound  int64         `binary:"fixed64"`
 BlockID   CanonicalBlockID
 Timestamp time.Time
 ChainID   string
}

CanonicalBlockID contains the block hash and canonical part-set header; it excludes BlockID.StateID. The proposal signature also excludes CoreChainLockedHeight. The exact signature-covered fields and replacement of unsigned fields from assembled block bytes are specified in Creating the proposal and Receiving the proposal and block.

The basic structural checks on the proposal before canonicalization include:

p.Type == 0x20
p.Height > 0
p.Round >= 0
p.POLRound >= -1
p.BlockID.IsComplete()

In other words, a proposal is valid for signing if it contains the type of a Proposal (0x20), has a positive, non-zero height, a non-negative round, a POLRound not less than -1, and a complete BlockID.

Votes

Sign bytes for votes are defined as CanonicalVote struct.

The canonical message is encoded using Protobuf. Its checksum is one input to the quorum signing digest, not the complete digest verified by BLS; see Block signature verification on light client. The schema is:

message CanonicalVote {
  SignedMsgType type   = 1;  // type alias for byte
  sfixed64      height = 2;
  sfixed64      round  = 3;
  // block_id is a checksum (sha256) of CanonicalBlockID for the block being voted on
  bytes block_id = 4 [(gogoproto.customname) = "BlockID"];
  // state_id is a checksum  (sha256) of StateID for the block being voted on
  bytes  state_id = 5 [(gogoproto.customname) = "StateID"];
  string chain_id = 99 [(gogoproto.customname) = "ChainID"];
}

block_id is a sha256 checksum of Protobuf-encoded CanonicalBlockID message:

message CanonicalBlockID {
  bytes                  hash            = 1;
  CanonicalPartSetHeader part_set_header = 2 [(gogoproto.nullable) = false];
}

message CanonicalPartSetHeader {
  uint32 total = 1;
  bytes  hash  = 2;
}

state_id is a sha256 checksum of Protobuf-encoded StateID message:

message StateID {
  // AppVersion used when generating the block, equals to Header.Version.App.
  fixed64 app_version = 1 [(gogoproto.customname) = "AppVersion"];
  // Height of block containing this state ID.
  fixed64 height = 2;
  // AppHash used in current block, equal to Header.AppHash. 32 bytes.
  bytes app_hash = 3 [(gogoproto.customname) = "AppHash"];
  // CoreChainLockedHeight for the block, equal to Header.CoreChainLockedHeight.
  fixed32 core_chain_locked_height = 4 [(gogoproto.customname) = "CoreChainLockedHeight"];
  // Time of the block.
  google.protobuf.Timestamp time = 5 [(gogoproto.nullable) = false];
}

A vote is valid if each of the following lines evaluates to true for vote v:

v.Type == 0x1 || v.Type == 0x2
v.Height > 0
v.Round >= 0
v.BlockID.IsNil() || v.BlockID.IsComplete()

In other words, a vote is valid for signing if it contains the type of a Prevote or Precommit (0x1 or 0x2, respectively), has a positive, non-zero height, a non-negative round, and an empty or valid BlockID.

Block signature verification on light client

The block signature in a commit is threshold-recovered from precommit shares and verified with the quorum's ThresholdPublicKey. Its signing context includes ChainID, the commit height and round, full BlockID, QuorumType, and QuorumHash.

Use MakeBlockSignItem or VoteBlockSignID in types/quorum_sign_data.go and types/vote.go to construct the digest:

  1. Build the precommit's canonical vote, including the canonical-block-ID checksum and state-ID hash.
  2. MakeBlockSignItem hashes the canonical vote sign bytes and derives BlockRequestID(height, round) using the dpbvote domain.
  3. SignItem.UpdateSignHash uses the quorum type, quorum hash, request ID and message hash to construct the Dash BLS signing hash, with the helper's byte-order conversions. Verify the signature against that digest and the threshold key.

Proposal signing uses ProposalBlockSignID and its own dpproposal request-ID domain, likewise bound to height, round and quorum context (types/proposal.go). Vote extensions have separate sign items; application-supplied raw-extension request IDs need not bind height and round. See Vote extensions.

This describes digest construction, not a complete light-client trust algorithm. Full-node commit acceptance also verifies every extension threshold signature, checks the held block's complete ID, and requires the application's verdict on the ordered commit extension vector; see Commit verification and Commit validity depends on the application. A valid block signature does not authenticate that vector's count and order.

Proposer heartbeats and round skip votes

From CONSENSUS_VERSION_2, the proposer of a round that waits for transactions signs a heartbeat every proposer_heartbeat, and a validator that hears none for the round's silence timeout signs a vote to skip the round. Both are signed like votes, with the validator's quorum key share over the DIP-7 sign hash of the quorum type, the quorum hash, a request ID, and the SHA256 checksum of the length-delimited, Protobuf-encoded sign bytes below.

A heartbeat's sign bytes are:

message CanonicalProposerHeartbeat {
  SignedMsgType             type      = 1;  // 0x30
  sfixed64                  height    = 2;
  sfixed64                  round     = 3;
  fixed64                   sequence  = 4;
  google.protobuf.Timestamp timestamp = 5;
  string                    chain_id  = 6;
}

Its request ID is the SHA256 checksum of "dphb", then the height as a little-endian uint64, the round as a little-endian uint32, and the sequence as a little-endian uint64. The sequence grows with every heartbeat of a round, so each heartbeat a proposer sends is a signing request of its own. A proposer that restarts with its clock gone back can repeat an ID for a heartbeat with another timestamp; the timestamp is in the sign bytes, so the signature still differs.

A round skip vote's sign bytes are the same for every validator voting to skip a round, so the votes of +2/3 recover into one threshold signature, the round skip certificate:

message CanonicalRoundSkip {
  SignedMsgType type     = 1;  // 0x31
  sfixed64      height   = 2;
  sfixed64      round    = 3;
  string        chain_id = 4;
}

Its request ID is the SHA256 checksum of "dpskip", then the height as a little-endian uint64 and the round as a little-endian uint32.

A heartbeat or skip vote is valid for signing if its height is positive and its round is not negative. Neither changes consensus state or conflicts with another message, so neither is subject to the double-signing rules below.

Invalid Votes and Proposals

Basic structure, signature verification and consensus admissibility are separate checks. Proposal verification failures do not automatically evict their sender; received commits evict only on ErrInvalidCommitSignature, and replay never evicts. Budget exhaustion is a local processing limit, not proof of peer fault. The exact policies are in Proposal acceptance, Vote admission, and Commit verification.

Double Signing

Signers must be careful not to sign conflicting messages, also known as "double signing" or "equivocating". Tenderdash has mechanisms to publish evidence of validators that signed conflicting votes, so they can be punished by the application. Note Tenderdash does not currently handle evidence of conflicting proposals, though it may in the future.

State

FilePV persists height, round, internal signing step, block sign bytes and block signature (FilePVLastSignState in privval/file.go). Its ordered steps are proposal, prevote and precommit; these are not the numeric SignedMsgType values. checkHRS rejects regressions and permits a matching height/round/step only for comparison with the persisted sign bytes.

Proposals

A new proposal signing request must pass the height/round/step checks. Conflicting canonical bytes at the same height/round/proposal step are refused. The current repeated-proposal return path has a documented signature-field discrepancy; it must not be assumed to return a valid reused signature.

Votes

For a new height or round, or a later internal step in the same height/round, FilePV can sign and persist the vote. For identical block sign bytes at an already-signed height/round/step, it reuses the stored block signature; different bytes are refused. Precommit extension signatures are regenerated, since the extensions are not part of the canonical block vote.

Nil and non-nil block IDs are different sign bytes: a signer cannot replace its nil vote with a block vote of the same type at the same height and round. The block-signature reuse rule permits recovery of an identical vote, not a second conflicting vote. See WAL catch-up. DashCoreSignerClient does not maintain FilePV's persisted state inside Tenderdash; signer-side protection must not be inferred from the presence of the client alone.

Other Rules

Signer height/round/step protection does not establish lock eligibility. The consensus state machine decides whether a block may be prevoted or precommitted; see Locking and the precommit decision. A nil polka does not unlock within a height, and relocking a block requires this round's proposal and application processing context.

Historical Tendermint discussions call unjustified lock changes “amnesia”; see the original fork-detection discussion. That history does not introduce an unlock transition or additional signer protection into the current implementation.