Data Structures

Here we describe the data structures in the Tenderdash blockchain and the rules for validating them.

The Tenderdash blockchains consists of a short list of data types:

ProTxHash

ProTxHash is 32 bytes array. Validator provides this parameter via a config.

Block

A block consists of a header, transactions, the commit of the previous block, an optional core chain lock, and a list of evidence of malfeasance (ie. signing conflicting votes).

NameTypeDescriptionValidation
HeaderHeaderHeader corresponding to the block. This field contains information used throughout consensus and other areas of the protocol. To find out what it contains, visit [header] (#header)Must adhere to the validation rules of header
DataDataData contains a list of transactions. The contents of the transaction is unknown to Tenderdash.This field can be empty or populated, but no validation is performed. Applications can perform validation on individual transactions prior to block creation using checkTx.
EvidenceEvidenceListEvidence contains a list of infractions committed by validators.Can be empty, but when populated the validations rules from evidenceList apply
LastCommitCommitThe threshold-signed commit of the previous block.Must not be nil, must carry no threshold block signature at the initial height, and must adhere to the validation rules of commit.
CoreChainLockCoreChainLock (optional)Core chain lock carried by the block.When present, must pass CoreChainLock.ValidateBasic.

Execution

Tenderdash uses same-block execution: PrepareProposal and ProcessProposal return this block's AppHash, transaction results, and pending validator/parameter changes. FinalizeBlock persists the accepted candidate; there is no ABCI Commit call. Changes from block h become active at h + 1.

See the canonical primary flow, proposal-validity summary, and commit application for execution, validation and persistence order. The local committed state is summarized in State; pending next-state values belong to CurrentRoundState.

A block header contains metadata about the block and about the consensus, as well as commitments to the data in the current block, the previous block, and the results returned by the application:

NameTypeDescriptionValidation
VersionVersionVersion defines the application and protocol version being used.Must adhere to the validation rules of Version
ChainIDStringChainID is the ID of the chain. This must be unique to your chain.ChainID must be at most 50 bytes.
Heightint64Height is the height for this header.Must be > 0, >= initialHeight, and == previous Height+1
CoreChainLockedHeightuint32Core chain height used to verify this block.Must match the block's core chain lock, or the state's last locked height without one (ValidateBlockChainLock).
TimeTimeThe timestamp is chosen by the proposer from its local clock (genesis time for the initial block) and accepted by validators only if timely; see Proposal timestamps. The historical median-based rule is described in the BFT-time section.Above the initial height, Time must be greater than the previous block's time. At the initial height, Time must be >= genesis time; a normal prevote additionally requires it to equal genesis time (rule P-Timely).
LastBlockIDBlockIDBlockID of the previous block.Must adhere to the validation rules of blockID. The first block has block.Header.LastBlockID == BlockID{}.
LastCommitHashslice of bytes ([]byte)Checksum of the last commit's threshold block signature (Commit.Hash).Empty or of length 32; must equal LastCommit.Hash()
DataHashslice of bytes ([]byte)MerkleRoot of the hash of transactions. Note: The transactions are hashed before being included in the merkle tree, the leaves of the Merkle tree are the hashes, not the transactions themselves.Empty or of length 32; must equal Data.Hash()
ValidatorsHashslice of bytes ([]byte)Merkle root of the current validator set's threshold public key and quorum hash (ValidatorSet.Hash). The validator list is not hashed, so its order, ascending ProTxHash (ValidatorsByProTxHashes), does not affect this value.Empty or of length 32
NextValidatorsHashslice of bytes ([]byte)Merkle root of the next validator set's threshold public key and quorum hash (ValidatorSet.Hash). The validator list is not hashed, so its order, ascending ProTxHash (ValidatorsByProTxHashes), does not affect this value.Empty or of length 32
ConsensusHashslice of bytes ([]byte)SHA-256 of the protobuf-encoded HashedParams subset of the current consensus parameters (HashConsensusParams).Empty or of length 32
NextConsensusHashslice of bytes ([]byte)The same hash over the consensus parameters of the next block.Empty or of length 32
AppHashslice of bytes ([]byte)Application state hash after executing this block's transactions, returned by the application from PrepareProposal and ProcessProposal.The application's response must be 32 bytes; must equal the application's answer (ValidateBlockWithRoundState).
ResultsHashslice of bytes ([]byte)Merkle root of this block's ExecTxResult values, keeping only Code, Data and GasUsed (TxResultsHash).Empty or of length 32; must equal the application's answer
EvidenceHashslice of bytes ([]byte)MerkleRoot of the evidence of Byzantine behaviour included in this block.Empty or of length 32; must equal Evidence.Hash()
ProposedAppVersionuint64Proposer's latest available application protocol version.
ProposerProTxHashProTxHashProTxHash of the original proposer of the block. Validator must be in the current validatorSet.Must be of length 32

Version

NOTE: that this is more specifically the consensus version and doesn't include information like the P2P Version. (TODO: we should write a comprehensive document about versioning that this can refer to)

NametypeDescriptionValidation
Blockuint64This number represents the version of the block protocol and must be the same throughout an operational networkMust be equal to protocol version being used in a network (block.Version.Block == state.Version.Consensus.Block)
Appuint64Application version used for this block; PrepareProposal can override it.Basic block validation does not require equality with the last committed application version (validateBlock in internal/state/validation.go).

BlockID

The BlockID contains two distinct Merkle roots of the block, the number of parts (ie. len(MakeParts(block))) and a state ID hash.

NameTypeDescriptionValidation
Hashslice of bytes ([]byte)MerkleRoot of all the fields in the header (ie. MerkleRoot(header).Empty (nil vote) or of length 32
PartSetHeaderPartSetHeaderUsed for secure gossiping of the block during consensus, is the MerkleRoot of the complete serialized block cut into parts (ie. MerkleRoot(MakeParts(block))).Must adhere to the validation rules of PartSetHeader
StateIDslice of bytes ([]byte)Hash of the StateID fields a light client needs to verify state; see Signing.Must be of length 32 when Hash is not empty

See MerkleRoot for details.

PartSetHeader

NameTypeDescriptionValidation
Totaluint32Total amount of parts for a blockMust be <= MaxBlockPartsCount; > 0 in a complete BlockID
Hashslice of bytes ([]byte)MerkleRoot of a serialized blockEmpty or of length 32

Part

Part defines a part of a block. In Tenderdash blocks are broken into parts for gossip.

NameTypeDescriptionValidation
indexuint32Index of this partMust equal Proof.Index
bytesbytesContent of this partMust be <= BlockPartSizeBytes long
proofProofMerkle proof of this partMust pass Proof.ValidateBasic

Time

Tenderdash uses the Google.Protobuf.Timestamp format, which uses two integers, one 64 bit integer for Seconds and a 32 bit integer for Nanoseconds.

Data

Data is just a wrapper for a list of transactions, where transactions are arbitrary byte arrays:

NameTypeDescriptionValidation
TxsMatrix of bytes ([][]byte)Slice of transactions.Validation does not occur on this field, this data is unknown to Tenderdash

Commit

Commit proves that a quorum decided a block: it carries the threshold-recovered signatures rather than one signature per validator.

NameTypeDescriptionValidation
Heightint64Height at which this commit was created.Must be >= 0
Roundint32Round that the commit corresponds to.Must be >= 0
BlockIDBlockIDThe blockID of the corresponding block.At height >= 1, must not be nil and must adhere to the validation rules of BlockID.
QuorumHashslice of bytes ([]byte)Hash of the quorum that signed the commit.
ThresholdBlockSignatureSignatureThreshold-recovered block signature.At height >= 1, must be of length 96
ThresholdVoteExtensionsArray of VoteExtensionThreshold-recovered vote extensions.No nil entries; every type must be a defined enum value

BlockIDFlag

BlockIDFlag is defined in types.proto, but Commit has no per-validator signatures and does not use it.

enum BlockIDFlag {
  BLOCK_ID_FLAG_UNKNOWN = 0;
  BLOCK_ID_FLAG_ABSENT  = 1; // signatures for other blocks are also considered absent
  BLOCK_ID_FLAG_COMMIT  = 2;
  BLOCK_ID_FLAG_NIL     = 3;
}

Vote

A vote is a signed message from a validator for a particular block. The vote includes information about the validator signing it. When stored in the blockchain or propagated over the network, votes are encoded in Protobuf. The vote extension is not part of the CanonicalVote.

NameTypeDescriptionValidation
TypeSignedMsgTypeEither prevote or precommit. SignedMsgTypeA Vote is valid if its corresponding fields are included in the enum signedMsgType
Heightint64Height for which this vote was created.Must be >= 0
Roundint32Round that the vote corresponds to.Must be >= 0
BlockIDBlockIDThe blockID of the corresponding block; zero for a nil vote.Must adhere to BlockID validation and be either nil or complete
ValidatorProTxHashProTxHashProTxHash of the validator.Length must be equal to 32
ValidatorIndexint32Index of the validator in the validator set at this height.Must be >= 0
BlockSignatureSignatureValidator's signature of the CanonicalVote sign bytes.Length must be > 0 and <= 96
VoteExtensionsArray of VoteExtensionVote extensions provided by the Application.Must be empty unless this is a non-nil precommit, which must pass VoteExtension validation

VoteExtension

NameTypeDescriptionValidation
TypeVoteExtensionTypeTHRESHOLD_RECOVER or THRESHOLD_RECOVER_RAW. DEFAULT exists in the enum but is not supported.Must not be DEFAULT
Extensionslice of bytes ([]byte)Extension data provided by the Application.Must be of length 32 for THRESHOLD_RECOVER_RAW
SignatureSignatureValidator's signature of the extension.Must be present when Extension is not empty; length must be <= 96
SignRequestIdslice of bytes ([]byte, optional)Application-supplied sign request ID.

CanonicalVote

CanonicalVote is for validator signing. This type will not be present in a block. For signing, votes are represented via CanonicalVote and encoded using protobuf via Vote.SignBytes, which includes the ChainID and omits ValidatorProTxHash and ValidatorIndex. block_id is a checksum of the CanonicalBlockID, and state_id is the BlockID's StateID.

message CanonicalVote {
  SignedMsgType type     = 1;
  sfixed64      height   = 2;
  sfixed64      round    = 3;
  bytes         block_id = 4;
  bytes         state_id = 5;
  string        chain_id = 99;
}

Vote.Verify(chainID, quorumType, quorumHash, pubKey, proTxHash) checks that proTxHash matches ValidatorProTxHash, then verifies the block signature, and any extension signatures, against the 48-byte BLS public key. See Signing.

Proposal

Proposal contains height and round for which this proposal is made, BlockID as a unique identifier of proposed block, timestamp, and POLRound (a so-called Proof-of-Lock (POL) round) that is needed for termination of the consensus. If POLRound >= 0, then BlockID corresponds to the block that is locked in POLRound. The message is signed by the validator private key.

NameTypeDescriptionValidation
TypeSignedMsgTypeRepresents a Proposal SignedMsgTypeMust be ProposalType signedMsgType
Heightint64Height for which this proposal was createdMust be >= 0
Roundint32Round that the proposal corresponds to.Must be >= 0
POLRoundint32Proof of lockMust be >= -1
BlockIDBlockIDThe blockID of the corresponding block.Must be complete and adhere to BlockID validation
TimestampTimeTimestamp chosen by the proposer; equal to the block time.Time
SignatureSignatureSignature by the proposer.Length of signature must be > 0 and <= 96
CoreChainLockedHeightuint32Core chain locked height used to sign and verify the block.Must not be MaxUint32
CoreChainLockUpdateCoreChainLock (optional)Core chain lock used to sign and verify the next block.When present, must pass CoreChainLock.ValidateBasic

SignedMsgType

Signed message type represents a signed messages in consensus.

enum SignedMsgType {

  SIGNED_MSG_TYPE_UNKNOWN = 0;
  // Votes
  SIGNED_MSG_TYPE_PREVOTE   = 1;
  SIGNED_MSG_TYPE_PRECOMMIT = 2;

  // Proposal
  SIGNED_MSG_TYPE_PROPOSAL = 32;

  // Proposer liveness, from CONSENSUS_VERSION_2
  SIGNED_MSG_TYPE_PROPOSER_HEARTBEAT = 48;
  SIGNED_MSG_TYPE_ROUND_SKIP = 49;
}

Signature

Signatures in Tenderdash are raw bytes representing the underlying signature. Consensus signatures are BLS12-381 signatures of 96 bytes (types.SignatureSize).

See the signature spec for more.

EvidenceList

EvidenceList is a simple wrapper for a list of evidence:

NameTypeDescriptionValidation
EvidenceArray of EvidenceList of verified evidenceValidation adheres to individual types of Evidence

Evidence

Evidence in Tenderdash is used to indicate breaches in the consensus by a validator.

More information on how evidence works in Tenderdash can be found here

DuplicateVoteEvidence

DuplicateVoteEvidence represents a validator that has voted for two different blocks in the same round of the same height. Votes are lexicographically sorted on BlockID.

NameTypeDescriptionValidation
VoteAVoteOne of the votes submitted by a validator when they equivocatedVoteA must adhere to Vote validation rules
VoteBVoteThe second vote submitted by a validator when they equivocatedVoteB must adhere to Vote validation rules
TotalVotingPowerint64The total power of the validator set at the height of equivocationMust be equal to nodes own copy of the data
ValidatorPowerint64Power of the equivocating validator at the heightMust be equal to the nodes own copy of the data
TimestampTimeTime of the block where the equivocation occurredMust be equal to the nodes own copy of the data

LightBlock

LightBlock is the core data structure of the light client. It combines two data structures needed for verification (signedHeader & validatorSet).

NameTypeDescriptionValidation
SignedHeaderSignedHeaderThe header and commit, these are used for verification purposes. To find out more visit light client docsMust not be nil and adhere to the validation rules of signedHeader
ValidatorSetValidatorSetThe validatorSet is used to help with verify that the validators in that committed the infraction were truly in the validator set.Must not be nil and adhere to the validation rules of validatorSet

The SignedHeader and ValidatorSet are linked by the hash of the validator set(SignedHeader.ValidatorsHash == ValidatorSet.Hash().

SignedHeader

The SignedhHeader is the header accompanied by the commit to prove it.

NameTypeDescriptionValidation
HeaderHeaderHeaderHeader cannot be nil and must adhere to the Header validation criteria
CommitCommitCommitCommit cannot be nil and must adhere to the Commit criteria

ValidatorSet

NameTypeDescriptionValidation
ValidatorsArray of validatorList of the active validators at a specific height, sorted by ascending ProTxHashThe list of validators can not be empty or nil and must adhere to the validation rules of validator
ProposervalidatorValidator at the set's proposer indexThe proposer index must be in range
ThresholdPublicKeypublic keyThreshold public key of the quorumMust pass ThresholdPublicKeyValid
QuorumTypeint32LLMQ type of the quorum
QuorumHashslice of bytes ([]byte)Hash of the quorumMust pass QuorumHashValid
HasPublicKeysboolWhether validators carry public keys, which holds when the local node is in the setWhen true, each public key must be valid
VotingPowerThresholduint64Minimum voting power required to commit; equals ValidatorParams.voting_power_threshold

Validator

NameTypeDescriptionValidation
ProTxHashProTxHashValidator's identityLength must be of size 32
PubKeyslice of bytes ([]byte)Validator's BLS public key; absent when the local node is not in the setLength must be 48 when validated
VotingPowerint64Validator's voting powercannot be < 0
NodeAddressValidatorAddressURI of the validator's nodeMust be valid when set

Address

Address is a type alias of a slice of bytes, calculated by hashing the public key using sha256 and truncating it to the first 20 bytes (crypto.AddressHash). Validators are identified by ProTxHash, not by address.

ConsensusParams

NameTypeDescriptionField Number
blockBlockParamsParameters limiting the size and gas of a block.1
evidenceEvidenceParamsParameters limiting the validity of evidence of byzantine behaviour.2
validatorValidatorParamsParameters limiting the types of public keys validators can use.3
versionVersionParamsThe ABCI application and consensus versions.4
synchronySynchronyParamsBounds under which a proposal timestamp is considered timely.5
timeoutTimeoutParamsTimeouts of the consensus steps.6
abciABCIParamsApplication Blockchain Interface options.7

BlockParams

NameTypeDescriptionField Number
max_bytesint64Max size of a block, in bytes.1
max_gasint64Max sum of GasWanted in a proposed block. NOTE: blocks that violate this may be committed if there are Byzantine proposers. It's the application's responsibility to handle this when processing a block!2

EvidenceParams

NameTypeDescriptionField Number
max_age_num_blocksint64Max age of evidence, in blocks.1
max_age_durationgoogle.protobuf.DurationMax age of evidence, in time. It should correspond with an app's "unbonding period" or other similar mechanism for handling Nothing-At-Stake attacks.2
max_bytesint64maximum size in bytes of total evidence allowed to be entered into a block3

ValidatorParams

NameTypeDescriptionField Number
pub_key_typesrepeated stringList of accepted public key types. Uses same naming as PubKey.Type.1
voting_power_thresholduint64 (optional)Minimum voting power required to commit a block. See voting_power_threshold.2

voting_power_threshold

A positive voting_power_threshold sets the vote-counting threshold T returned by ValidatorSet.QuorumVotingThresholdPower; zero uses the quorum-type threshold. Every validator contributes power 100. An explicit value must not exceed total power, but a threshold below the strict BFT floor is only warned about.

This override does not lower the separate BLS recovery threshold R returned by QuorumTypeThresholdVotingPower. Prevotes expose a majority at T; precommits also require successful recovery and verification of threshold signatures. A low vote-counting threshold alone does not let one signature share produce a commit. A threshold above R disables round skipping (Proposer liveness). See Threshold recovery for the canonical extension-group and recovery rules, and Commit threshold is configurable below the BFT bound for the documented safety limitation. Changes to this live consensus parameter must not be assumed incapable of changing consensus behavior merely because a parameter is absent from a particular header-hash subset.

VersionParams

NameTypeDescriptionField Number
app_versionuint64The ABCI application version.1
consensus_versionConsensusVersionVersion of the consensus protocol, selecting the proposer strategy. CONSENSUS_VERSION_2 also enables proposer liveness.2

SynchronyParams

NameTypeDescriptionField Number
message_delaygoogle.protobuf.DurationBound for how long a proposal message may take to reach all validators on a newtork and still be considered valid.1
precisiongoogle.protobuf.DurationBound for how skewed a proposer's clock may be from any validator on the network while still producing valid proposals.2

TimeoutParams

NameTypeDescriptionField Number
proposegoogle.protobuf.DurationParameter that, along with propose_delta, configures the timeout for the propose step of the consensus algorithm.1
propose_deltagoogle.protobuf.DurationParameter that, along with propose, configures the timeout for the propose step of the consensus algorithm.2
votegoogle.protobuf.DurationParameter that, along with vote_delta, configures the timeout for the prevote and precommit step of the consensus algorithm.3
vote_deltagoogle.protobuf.DurationParameter that, along with vote, configures the timeout for the prevote and precommit step of the consensus algorithm.4
proposer_heartbeatgoogle.protobuf.DurationHow often the proposer of a round that waits for transactions sends a heartbeat. Used from CONSENSUS_VERSION_2; unset means derived (see Parameters).7
proposer_silencegoogle.protobuf.DurationHow long a validator waits without a heartbeat before it votes to skip the round; grows by proposer_heartbeat per round. Used from CONSENSUS_VERSION_2; unset means derived.8

ABCIParams

NameTypeDescriptionField Number
recheck_txboolIndicates whether to run CheckTx on all remaining transactions after every execution of a block1

Proof

NameTypeDescriptionField Number
totalint64Total number of items.1
indexint64Index item to prove.2
leaf_hashbytesHash of item value.3
auntsrepeated bytesHashes from leaf's sibling to a root's child.4