CINXE.COM

<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link rel="stylesheet" href="/css/layout.css?1738557326388"> <link rel="stylesheet" href="/css/nav.css?1738557326388"> <link rel="stylesheet" href="/css/style.css?1738557326388"> <link rel="stylesheet" href="/css/prismjs@1.24-themes-prism.css"> <title>IPLD ♦ </title> </head> <body> <header> <div class="sidebar-button" onclick="document.getElementById('sidebar').classList.toggle('sidebar-open')"> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"> <path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path> </svg> </div> <a href="/" class="logo">IPLD</a> <aside id=breadcrumbs> <ul> <li><a href="/specs">specs</a></li> <li><a href="/specs/codecs">codecs</a></li> <li><a href="/specs/codecs/dag-cosmos">dag-cosmos</a></li> <li><a href="/specs/codecs/dag-cosmos/tendermint_chain/">tendermint_chain</a></li> </ul> </aside> </header> <aside id=sidebar> <nav> <ul> <li> <a href="/docs/">Docs</a><ul> <li> <a href="/docs/intro/">Intro</a><ul> <li> <a href="/docs/intro/hello-world/">Hello, World</a></li> <li> <a href="/docs/intro/primer/">The Brief Primer</a></li> <li> <a href="/docs/intro/ecosystem/">InterPlanetary Ecosystem Overview</a></li> <li> <a href="/docs/intro/community/">Finding Community</a></li></ul></li> <li> <a href="/docs/motivation/">Motivation</a><ul> <li> <a href="/docs/motivation/benefits-of-content-addressing/">Benefits of Content Addressing</a></li> <li> <a href="/docs/motivation/data-to-data-structures/">From Data to Data Structures</a></li></ul></li> <li> <a href="/docs/codecs/">Codecs</a><ul> <li> <a href="/docs/codecs/known/">Known Codecs</a><ul> <li> <a href="/docs/codecs/known/dag-cbor/">DAG-CBOR</a></li> <li> <a href="/docs/codecs/known/dag-json/">DAG-JSON</a></li> <li> <a href="/docs/codecs/known/dag-pb/">DAG-PB</a></li></ul></li></ul></li> <li> <a href="/docs/data-model/">Data Model</a><ul> <li> <a href="/docs/data-model/node/">Nodes</a></li> <li> <a href="/docs/data-model/kinds/">Kinds</a></li> <li> <a href="/docs/data-model/pathing/">Pathing</a></li> <li> <a href="/docs/data-model/traversal/">Traversal</a></li></ul></li> <li> <a href="/docs/advanced-data-layouts/">Advanced Data Layouts</a><ul> <li> <a href="/docs/advanced-data-layouts/intro/">Intro to ADLs</a></li> <li> <a href="/docs/advanced-data-layouts/naming/">ADL Naming</a></li> <li> <a href="/docs/advanced-data-layouts/signalling/">Signalling ADLs</a></li> <li> <a href="/docs/advanced-data-layouts/dynamic-loading/">Dynamic Loading</a></li> <li> <a href="/docs/advanced-data-layouts/known/">Known ADLs</a></li></ul></li> <li> <a href="/docs/schemas/">Schemas</a><ul> <li> <a href="/docs/schemas/intro/">Introduction</a><ul> <li> <a href="/docs/schemas/intro/compare/">compare</a></li> <li> <a href="/docs/schemas/intro/goals/">Goals</a></li> <li> <a href="/docs/schemas/intro/feature-summary/">Feature Summary</a></li></ul></li> <li> <a href="/docs/schemas/features/">Features</a><ul> <li> <a href="/docs/schemas/features/typekinds/">Type Kinds</a></li> <li> <a href="/docs/schemas/features/representation-strategies/">Representation Strategies</a></li> <li> <a href="/docs/schemas/features/links/">Links</a></li> <li> <a href="/docs/schemas/features/indicating-adls/">Using ADLs in Schemas</a></li></ul></li> <li> <a href="/docs/schemas/using/">Using Wisely</a><ul> <li> <a href="/docs/schemas/using/authoring-guide/">Authoring Guide</a></li> <li> <a href="/docs/schemas/using/migrations/">Migrations</a></li></ul></li></ul></li> <li> <a href="/docs/synthesis/">Synthesis</a><ul> <li> <a href="/docs/synthesis/gtd/">Getting Things Done</a></li> <li> <a href="/docs/synthesis/building-in-alignment/">Building in Alignment</a></li> <li> <a href="/docs/synthesis/how-ipfs-web-gateways-work/">How IPFS Web Gateways Work</a></li> <li> <a href="/docs/synthesis/encryption/">Working With Encryption</a></li></ul></li></ul></li> <li> <a href="/specs/">Specs</a><ul> <li> <a href="/specs/about/">About the Specifications</a></li> <li> <a href="/specs/codecs/">Codecs</a><ul> <li> <a href="/specs/codecs/dag-cbor/">DAG-CBOR</a><ul> <li> <a href="/specs/codecs/dag-cbor/spec/">Spec</a></li> <li> <a href="/specs/codecs/dag-cbor/fixtures/">DAG-CBOR Test Fixtures</a><ul> <li> <a href="/specs/codecs/dag-cbor/fixtures/cross-codec/">cross-codec</a></li></ul></li></ul></li> <li> <a href="/specs/codecs/dag-cosmos/">DAG-COSMOS</a><ul> <li> <a href="/specs/codecs/dag-cosmos/basic_types/">basic_types</a></li> <li> <a href="/specs/codecs/dag-cosmos/cosmos_state/">cosmos_state</a></li> <li> <a href="/specs/codecs/dag-cosmos/crypto_types/">crypto_types</a></li> <li class="active-page"> <a href="/specs/codecs/dag-cosmos/tendermint_chain/">tendermint_chain</a></li> <li> <a href="/specs/codecs/dag-cosmos/typed_protobuf/">typed_protobuf</a></li></ul></li> <li> <a href="/specs/codecs/dag-eth/">DAG-ETH</a><ul> <li> <a href="/specs/codecs/dag-eth/basic_types/">basic_types</a></li> <li> <a href="/specs/codecs/dag-eth/chain/">chain</a></li> <li> <a href="/specs/codecs/dag-eth/convenience_types/">convenience_types</a></li> <li> <a href="/specs/codecs/dag-eth/state/">state</a></li></ul></li> <li> <a href="/specs/codecs/dag-jose/">DAG-JOSE</a><ul> <li> <a href="/specs/codecs/dag-jose/spec/">Spec</a></li> <li> <a href="/specs/codecs/dag-jose/fixtures/">fixtures</a></li></ul></li> <li> <a href="/specs/codecs/dag-json/">DAG-JSON</a><ul> <li> <a href="/specs/codecs/dag-json/spec/">Spec</a></li> <li> <a href="/specs/codecs/dag-json/fixtures/">DAG-JSON Test Fixtures</a><ul> <li> <a href="/specs/codecs/dag-json/fixtures/cross-codec/">cross-codec</a></li></ul></li></ul></li> <li> <a href="/specs/codecs/dag-pb/">DAG-PB</a><ul> <li> <a href="/specs/codecs/dag-pb/spec/">Spec</a></li> <li> <a href="/specs/codecs/dag-pb/fixtures/">DAG-PB Test Fixtures</a><ul> <li> <a href="/specs/codecs/dag-pb/fixtures/cross-codec/">cross-codec</a></li></ul></li></ul></li></ul></li> <li> <a href="/specs/advanced-data-layouts/">Advanced Data Layouts</a><ul> <li> <a href="/specs/advanced-data-layouts/fbl/">FBL ADL</a><ul> <li> <a href="/specs/advanced-data-layouts/fbl/spec/">spec</a></li></ul></li> <li> <a href="/specs/advanced-data-layouts/hamt/">HAMT ADL</a><ul> <li> <a href="/specs/advanced-data-layouts/hamt/spec/">spec</a></li> <li> <a href="/specs/advanced-data-layouts/hamt/fixture/">HashMap (HAMT) Test Fixtures</a><ul> <li> <a href="/specs/advanced-data-layouts/hamt/fixture/alice-words/">alice-words</a></li></ul></li></ul></li></ul></li> <li> <a href="/specs/schemas/">Schemas</a><ul> <li> <a href="/specs/schemas/prelude/">prelude</a></li></ul></li> <li> <a href="/specs/transport/">Transports</a><ul> <li> <a href="/specs/transport/car/">CAR</a><ul> <li> <a href="/specs/transport/car/carv1/">CARv1 Specification</a></li> <li> <a href="/specs/transport/car/carv2/">CARv2 Specification</a></li> <li> <a href="/specs/transport/car/fixture/">CAR Test Fixtures</a><ul> <li> <a href="/specs/transport/car/fixture/carv1-basic/">carv1-basic</a></li> <li> <a href="/specs/transport/car/fixture/carv2-basic/">carv2-basic</a></li></ul></li></ul></li> <li> <a href="/specs/transport/graphsync/">Graphsync</a><ul> <li> <a href="/specs/transport/graphsync/known_extensions/">known_extensions</a></li></ul></li> <li> <a href="/specs/transport/trustless-pathing/">Trustless Pathing</a><ul> <li> <a href="/specs/transport/trustless-pathing/fixtures/">Trustless Pathing Fixtures</a><ul> <li> <a href="/specs/transport/trustless-pathing/fixtures/unixfs_20m_variety/">unixfs_20m_variety</a></li></ul></li></ul></li></ul></li> <li> <a href="/specs/selectors/">Selectors</a><ul> <li> <a href="/specs/selectors/fixtures/">fixtures</a><ul> <li> <a href="/specs/selectors/fixtures/selector-fixtures-1/">selector-fixtures-1</a></li> <li> <a href="/specs/selectors/fixtures/selector-fixtures-adl/">selector-fixtures-adl</a></li> <li> <a href="/specs/selectors/fixtures/selector-fixtures-recursion/">selector-fixtures-recursion</a></li></ul></li></ul></li> <li> <a href="/specs/patch/">Patch</a><ul> <li> <a href="/specs/patch/fixtures/">IPLD Patch Test Fixtures</a><ul> <li> <a href="/specs/patch/fixtures/fixtures-1/">fixtures-1</a></li></ul></li></ul></li></ul></li> <li> <a href="/libraries/">Libraries</a><ul> <li> <a href="/libraries/golang/">Golang</a></li> <li> <a href="/libraries/java/">Java</a></li> <li> <a href="/libraries/javascript/">JavaScript</a></li> <li> <a href="/libraries/python/">Python</a></li> <li> <a href="/libraries/rust/">Rust</a></li></ul></li> <li> <a href="/design/">Design</a><ul> <li> <a href="/design/objectives/">Objectives</a></li> <li> <a href="/design/concepts/">Concepts</a><ul> <li> <a href="/design/concepts/type-theory-glossary/">type-theory-glossary</a></li></ul></li> <li> <a href="/design/libraries/">Libraries</a><ul> <li> <a href="/design/libraries/nodes-and-kinds/">nodes-and-kinds</a></li></ul></li> <li> <a href="/design/tricky-choices/">Tricky Choices</a><ul> <li> <a href="/design/tricky-choices/dag-pb-forms-impl-and-use/">dag-pb-forms-impl-and-use</a></li> <li> <a href="/design/tricky-choices/map-key-domain/">map-key-domain</a></li> <li> <a href="/design/tricky-choices/numeric-domain/">numeric-domain</a></li> <li> <a href="/design/tricky-choices/ordering/">ordering</a></li> <li> <a href="/design/tricky-choices/string-domain/">string-domain</a></li></ul></li> <li> <a href="/design/open-research/">Open Research</a><ul> <li> <a href="/design/open-research/ADL-autoexecution/">ADL autoexecution</a></li></ul></li></ul></li> <li> <a href="/tools/">Tools</a></li> <li> <a href="/glossary/">Glossary</a></li> <li> <a href="/media/">Media</a></li> <li> <a href="/FAQ/">FAQ</a></li></ul> </nav> </aside> <main> <div class=content> <h1>Tendermint Chain Data Structures</h1> Tendermint is a generic proof-of-stake consensus layer that provides Byzantine fault tolerant state machine replication for any state machine that conforms to the Application BlockChain Interface (ABCI) or ABCI++. For more details on Tendermint and ABCI/ABCI++, see the specification <a href="https://github.com/tendermint/tendermint/tree/master/spec">here</a>. <h2 id="tendermint-merkle-tree-nodes" tabindex="-1"><a class="header-anchor" href="#tendermint-merkle-tree-nodes">Tendermint Merkle Tree Nodes</a></h2> A Merkle tree node is a single node in a Merkle tree. A Merkle node is referenced by its hash. The top-level node in the tree is the root node, its hash is the Merkle root. Tendermint uses the RFC 6962 specification of a merkle tree, with SHA256 as the hash function. <ul> <li>The hash of an inner node is <code>SHA256(0x01 || left_hash || right_hash)</code>.</li> <li>The hash of a leaf node is <code>SHA256(0x00 || value)</code>.</li> <li>The multicodec type used for a Merkle tree will depend on the content it stores</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch">type MerkleTreeNode union { | MerkleTreeRootNode "root" | MerkleTreeInnerNode "inner" | MerkleTreeLeafNode "leaf" } representation keyed # MerkleTreeRootNode is the top-most node in a merkle tree; the root node of the tree. # It can be a leaf node if there is only one value in the tree # We explicitly type the root node for the purposes of handling Block and Header marshalling # since entire sub-dags need to be collapsed down and encoded into the protobuf object we need to be # able to check that the ipld.Node provided to the marshaller is a root node type MerkleTreeRootNode MerkleTreeNode # MerkleTreeInnerNode nodes contain two byte arrays which contain the hashes which link its two child nodes. type MerkleTreeInnerNode struct { Left nullable &MerkleTreeNode Right nullable &MerkleTreeNode } # Value union type used to handle the different values stored in leaf nodes in the different merkle trees type Value union { | SimpleValidator "validator" | Evidence "evidence" | TypedTxCID "tx" | Part "part" | ResponseDeliverTx "result" | Bytes "header" | CommitSig "commit" } representation keyed # MerkleTreeLeafNode is a single byte array containing the value stored at that leaf # Often times this "value" will be a hash of content rather than the content itself type MerkleTreeLeafNode struct { Value Value }</code></pre> <h2 id="tendermint-block" tabindex="-1"><a class="header-anchor" href="#tendermint-block">Tendermint Block</a></h2> A block consists of a header, transactions, votes (the commit), and a list of evidence of malfeasance (i.e. signing conflicting votes). Blocks are indirectly content-hash referenced by the root of a Merkle tree composed of its parts. In order to support this indirect content referencing, we introduce a new multihash type: SHA256_MERKLE. This multihash type stipulates that the hash is an SHA256 RFC 6962 specification Merkle tree root hash. <pre class="language-ipldsch"><code class="language-ipldsch"># BlockCID is a CID link to a Tendermint block, this link is indirect by means of reference to the root node of a Part # Merkle tree (formed from all of the parts of a complete block) rather than a direct reference by hash of the block itself # This CID is composed of the SHA256 multihash of the root node in the Block Part Merkle Tree and the TendermintBlock codec (tbd) # Part merkle tree is a Merkle tree built from the PartSet, each leafs contains Part.Bytes type BlockCID &Block # Block defines the atomic unit of a Tendermint blockchain type Block struct { Header Header Data Txs Evidence EvidenceList LastCommit Commit } # BlockID contains two distinct Merkle roots of the block. type BlockID struct { HeaderCID HeaderFieldTreeCID PartSetHeader PartSetHeader } # PartSetHeader is used for secure gossiping of the block during consensus # It contains the Merkle root of the complete serialized block cut into parts (ie. MerkleRoot(MakeParts(block))). type PartSetHeader struct { Total Uint BlockCID BlockPartTreeCID } # PartSet is the complete set of parts for a header type PartSet [Part] # Part is a section of bytes of a complete protobuf serialized block type Part struct { Index Uint Bytes HexBytes Proof Proof }</code></pre> <h2 id="tendermint-block-part-tree" tabindex="-1"><a class="header-anchor" href="#tendermint-block-part-tree">Tendermint Block Part Tree</a></h2> This is the IPLD schema for Block Part Merkle Tree nodes. This is an alias for a <code>MerkleTreeNode</code> where the <code>Value</code> union type stored in a leaf node is of type <code>Part</code>. <ul> <li>The Block Part Merkle Tree is a Merkle tree built from the set of block <code>Part</code>s, these are byte segments of the serialized block.</li> <li>The block binary is segmented across parts based on a chunk size. In this manner, the fields of the block do not map to specific leaves but instead the binary for a specific field can be spread across multiple leaves and a single leaf may contain chunks of different fields.</li> <li>CID links to a <code>BlockPartTreeNode</code> use an SHA256 multihash of the node binary and the TendermintBlockPartTree codec (tbd).</li> <li>The root node of this tree for block <code>n-1</code> is referenced in a Tendermint <code>PartSetHeader</code> by the <code>BlockCID</code> at block <code>n</code>.</li> <li>The <code>PartSetHeader</code> is part of the <code>BlockID</code>.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch"># BlockPartTreeNode is an IPLD block for a node in a Block Part merkle tree type BlockPartTreeNode MerkleTreeNode # BlockPartTreeCID is a CID link to a node of a Block Part merkle tree type BlockPartTreeCID &BlockPartTreeNode</code></pre> <h2 id="tendermint-header" tabindex="-1"><a class="header-anchor" href="#tendermint-header">Tendermint Header</a></h2> 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. Similar to blocks, headers are indirectly content-hash referenced by the root of a Merkle tree composed of the header's separate fields. <pre class="language-ipldsch"><code class="language-ipldsch"># HeaderCID is a CID link to a Tendermint header, this link is indirect by means of a reference to the root node of a # Header merkle tree (formed from all the fields of a header) rather than a direct reference by hash of the header itself # This CID is composed of the SHA256 multihash of the root node in the Header Merkle Tree and the TendermintHeader codec (tbd) # Header merkle tree is a Merklization of all of the fields in the header, each leaf stores a single protobuf encoded field # and the order of these fields in the Merkle Tree corresponds with their order in the header object type HeaderCID &Header # Header defines the structure of a Tendermint block header type Header struct { # basic block info Version Version ChainID String Height Int Time Time # prev block info # the first block has an empty BlockID struct as LastBlockID LastBlockID BlockID # hashes of block data LastCommitCID CommitTreeCID # CID link to the root node of a Merkle Tree formed from the last block's set of commit signatures DataCID TxTreeCID # CID link to the root node of a Merkle Tree formed from this block's set of transactions # hashes from the app output from the prev block ValidatorsCID ValidatorTreeCID # CID link to the root node of a Merkle Tree formed from this block's validator set NextValidatorsCID ValidatorTreeCID # CID link to the root node of a Merkle Tree formed from the next validator set ConsensusCID HashedParamsCID # CID link to HashedParams AppCID AppStateTreeCID # State Root from the state machine # root hash of all results from the txs from the previous block LastResultsCID ResultTreeCID # CID link to the root node of a Merkle Tree formed from the last block's set of results # consensus info EvidenceCID EvidenceTreeCID # CID link to the root node of a Merkle Tree formed from this block's set of evidence ProposerAddress Address # Address of the original proposer of this block, which must a validator in the current validator set }</code></pre> <h2 id="tendermint-header-field-tree" tabindex="-1"><a class="header-anchor" href="#tendermint-header-field-tree">Tendermint Header Field Tree</a></h2> This is the IPLD schema for header field tree nodes. This is an alias for a <code>MerkleTreeNode</code> where the <code>Value</code> union type stored in a leaf node is of type <code>Bytes</code>. <ul> <li>The Header Field merkle tree is a Merkle tree built from the individual fields of a <code>Header</code>.</li> <li>Each protobuf serialized field is stored in a leaf node, in the order they appear in the <code>Header</code> object. As such, each leaf stores a different type of value.</li> </ul> <pre><code>LeafIndex0 = protobuf(Version) LeafIndex1 = protobuf(ChainID) LeafIndex2 = protobuf(Height) LeafIndex3 = protobuf(Time) LeafIndex4 = protobuf(LastBlockID) LeafIndex5 = protobuf(LastCommitID) LeafIndex6 = protobuf(DataCID) LeafIndex7 = protobuf(ValidatorsCID) LeafIndex8 = protobuf(NextValidatorsCID) LeafIndex9 = protobuf(ConsensusCID) LeafIndex10 = protobuf(AppCID) LeafIndex11 = protobuf(LastResultsCID) LeafIndex12 = protobuf(EvidenceCID) LeafIndex13 = protobuf(ProsperAddress) </code></pre> For a visual representation of the above, see the included <a href="../tendermint_dag.png">diagram</a>. <ul> <li>CID links to a <code>HeaderFieldTreeNode</code> use an SHA256 multihash of the node binary and the TendermintHeaderFieldTree codec (tbd).</li> <li>The root node of this tree at block <code>n-1</code> is referenced in a Tendermint <code>BlockID</code> by the <code>BlockCID</code> at block <code>n</code>.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch"># HeaderFieldTreeNode is an IPLD block for a node in a Header Field merkle tree type HeaderFieldTreeNode MerkleTreeNode # HeaderFieldTreeCID is a CID link to a node of a Header Field merkle tree type HeaderFieldTreeCID &HeaderFieldTreeNode</code></pre> <h2 id="tendermint-light-block" tabindex="-1"><a class="header-anchor" href="#tendermint-light-block">Tendermint Light Block</a></h2> LightBlock is the core data structure of the light client. It combines two data structures needed for verification (SignedHeader & ValidatorSet). CID links to LightBlock use the SHA256 multihash and the LightBlock codec (tbd). <pre class="language-ipldsch"><code class="language-ipldsch"># LightBlock is a SignedHeader and a ValidatorSet. # It is the basis of the light client type LightBlock struct { SignedHeader SignedHeader ValidatorSet ValidatorSet } # SignedHeader is a header along with the commits that prove it. type SignedHeader struct { Header Header Commit Commit }</code></pre> <h2 id="tendermint-validator-and-validator-set" tabindex="-1"><a class="header-anchor" href="#tendermint-validator-and-validator-set">Tendermint Validator and Validator Set</a></h2> A Validator object is used to uniquely identify a Tendermint validator. A Validator Set is used to help verify that the validators that committed a infraction were truly in the validator set. <pre class="language-ipldsch"><code class="language-ipldsch"># ValidatorSet represent a set of Validators 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). type ValidatorSet struct { Validators Validators Proposer Validator } # Validators is a list of validators types Validators [Validator] # Volatile state for each Validator # NOTE: The Address and ProposerPriority is not included in Validator.Hash(); # make sure to update that method if changes are made here type Validator struct { Address Address # Not included in the hash PubKey PubKey VotingPower Int ProposerPriority Int # Not included in the hash } # SimpleValidator contains only the consensus fields of a Validator type SimpleValidator struct { PubKey PubKey VotingPower Int }</code></pre> <h2 id="tendermint-validator-tree" tabindex="-1"><a class="header-anchor" href="#tendermint-validator-tree">Tendermint Validator Tree</a></h2> This is the IPLD schema for validator tree nodes. This is an alias for a <code>MerkleTreeNode</code> where the <code>Value</code> union type stored in a leaf node is <code>SimpleValidator</code>. <ul> <li>The Validator Merkle Tree is a Merkle Tree built from the set of <code>SimpleValidator</code>s for the given block</li> <li>The validators are first sorted by voting power (descending), then by address (ascending) to determine their index in the tree.</li> <li>Leaves contain a protobuf serialized <code>SimpleValidator</code> object, which contains consensus fields for a validator.</li> <li>CID links to a <code>ValidatorTreeNode</code> use an SHA256 multihash of the node binary and the TendermintValidatorTree codec (tbd).</li> <li>The root node of this tree is referenced in a Tendermint <code>Header</code> by the <code>ValidatorsCID</code> for the current set at the current block height and the <code>NextValidatorsCID</code> for the set at the next block height.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch"># ValidatorTreeNode is an IPLD block for a node in a Validator merkle tree type ValidatorTreeNode MerkleTreeNode # ValidatorTreeCID is a CID link to a node of a Validator merkle tree type ValidatorTreeCID &ValidatorTreeNode</code></pre> <h2 id="tendermint-evidence-list-and-evidence" tabindex="-1"><a class="header-anchor" href="#tendermint-evidence-list-and-evidence">Tendermint Evidence List and Evidence</a></h2> Evidence in Tendermint is used to indicate breaches in the consensus by a validator. <pre class="language-ipldsch"><code class="language-ipldsch"># EvidenceList is a simple wrapper for a list of evidence type EvidenceList [Evidence] # Evidence in Tendermint is used to indicate breaches in the consensus by a validator # Currently there are two types of Evidence type Evidence union { | DuplicateVoteEvidence "duplicate" | LightClientAttackEvidence "light" } representation keyed # 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. type `DuplicateVoteEvidence` struct { VoteA Vote VoteB Vote # abci specific information TotalVotingPower Int ValidatorPower Int Timestamp Time } # Vote represents a prevote, precommit, or commit vote from validators for # consensus. type Vote struct { SMType SignedMsgType Height Int Round Int BlockID BlockID Timestamp Time ValidatorAddress Address ValidatorIndex Int Signature Signature } # SignedMsgType is the type of signed message in the consensus. type SignedMsgType enum { | UnknownType ("0") | PrevoteType ("1") | PrecommitType ("2") | ProposalType ("32") } representation int # LightClientAttackEvidence is a generalized evidence that captures all forms of known attacks on # a light client such that a full node can verify, propose and commit the evidence on-chain for # punishment of the malicious validators. There are three forms of attacks: Lunatic, Equivocation and Amnesia. type LightClientAttackEvidence struct { ConflictingBlock LightBlock CommonHeight Int # abci specific information ByzantineValidators [Validator] # Validators in the validator set that misbehaved in creating the conflicting block TotalVotingPower Int # Total voting power of the validator set at the common height Timestamp Time # Timestamp of the block at the common height }</code></pre> <h2 id="tendermint-evidence-tree" tabindex="-1"><a class="header-anchor" href="#tendermint-evidence-tree">Tendermint Evidence Tree</a></h2> This is the IPLD schema for evidence tree nodes. This is an alias for a <code>MerkleTreeNode</code> where the <code>Value</code> union type stored in a leaf node is <code>Evidence</code>. <ul> <li>The Evidence Merkle Tree is Merkle Tree built from the list of Evidence of Byzantine behaviour included in this block.</li> <li>Leaves contain a protobuf serialized <code>Evidence</code> object, either <code>DuplicateVoteEvidence</code> or <code>LightClientAttackEvidence</code>.</li> <li>CID links to a <code>EvidenceTreeNode</code> use an SHA256 multihash of the node binary and the TendermintEvidenceTree codec (tbd).</li> <li>The root node of this tree is referenced in a Tendermint <code>Header</code> by the <code>EvidenceCID</code>.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch"># EvidenceTreeNode is an IPLD block for a node in an Evidence merkle tree type EvidenceTreeNode MerkleTreeNode # EvidenceTreeCID is a CID link to a node of an Evidence merkle tree type EvidenceTreeCID &EvidenceTreeNode</code></pre> <h2 id="tendermint-transaction" tabindex="-1"><a class="header-anchor" href="#tendermint-transaction">Tendermint Transaction</a></h2> Transactions in Tendermint are unstructured byte arrays from the perspective of the Tendermint client. This is necessary to support any arbitrary ABCI/ABCI++ compliant state machine. The state machine is responsible for decoding and applying these transactions in a deterministic capacity. For CosmosSDK based state machines these transactions are always protobuf encoded objects, if we accept this as the general case we can provide rich content typing using the protobuf typing scheme described in <a href="../typed_protobuf">typed_protobuf.md</a>. <pre class="language-ipldsch"><code class="language-ipldsch"># TypedTx is an alias for a TypedProtobuf object type TypedTx TypedProtobuf # TypedTxCID is an alias for a TypedProtobufCID # This CID is composed of the SHA2-256-Ignore32BytePrefix multihash of the TypedProtobuf IPLD block binary and the TypedProtobuf codec (tbd) type TypedTxCID TypedProtobufCID</code></pre> <h2 id="tendermint-tx-tree" tabindex="-1"><a class="header-anchor" href="#tendermint-tx-tree">Tendermint Tx Tree</a></h2> This is the IPLD schema for tx tree nodes. This is an alias for a <code>MerkleTreeNode</code> where the <code>Value</code> union type stored in a leaf node is a <code>TxTreeCID</code>. <ul> <li>The Tx Merkle Tree is Merkle Tree built from the list of transactions included in this block, ordered by their index in the block.</li> <li>A transaction is an unstructured byte array, it's decoding is dependent on the state machine it is intended for.</li> <li>Leaves contain a hash link (<code>TypedTxCID</code>) to a transaction rather than the transaction itself.</li> <li>CID links to a <code>TxTreeNode</code> use an SHA256 multihash of the node binary and the TxTree codec (tbd).</li> <li>The root node of this tree is referenced in a Tendermint <code>Header</code> by the <code>DataCID</code>.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch"># TxTreeNode is an IPLD block for a node in a Tx merkle tree type TxTreeNode MerkleTreeNode # TxTreeCID is a CID link to a node in a Tx merkle tree type TxTreeCID &TxTreeNode</code></pre> <h2 id="tendermint-result" tabindex="-1"><a class="header-anchor" href="#tendermint-result">Tendermint Result</a></h2> The result object contains the consensus fields of an ABCI ResponseDeliverTx. <pre class="language-ipldsch"><code class="language-ipldsch"># ResponseDeliverTx are the consensus fields of an ABCI ResponseDeliverTx, that are included in the ResultTree type ResponseDeliverTx struct { Code Uint Data Bytes GasWanted Int GasUsed Int }</code></pre> <h2 id="tendermint-result-tree" tabindex="-1"><a class="header-anchor" href="#tendermint-result-tree">Tendermint Result Tree</a></h2> This is the IPLD schema for result tree nodes. This is an alias for a <code>MerkleTreeNode</code> where the <code>Value</code> union type stored in a leaf node is a <code>ResponseDeliverTx</code>. <ul> <li>The Result Merkle Tree is Merkle tree built from the list of the consensus results included in the previous block, ordered by their index in the block.</li> <li>Leaves contain a protobuf serialized <code>ResponseDeliverTx</code>, this object contains only the consensus fields of the ABCI <code>ResponseDeliverTx</code>.</li> <li>CID links to a <code>ResultTreeNode</code> use an SHA256 multihash of the node binary and the TendermintResultTree codec (tbd).</li> <li>The root node of this tree is referenced in a Tendermint <code>Header</code> by the <code>LastResultsCID</code>.</li> <li>The first block has an empty Result tree. The <code>LastResultsCID</code> will be derived from the hash of an empty input, for RFC-6962 conformance.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch"># ResultTreeNode is an IPLD block for a node in a Result merkle tree type ResultTreeNode MerkleTreeNode # ResultTreeCID is a CID link to a node in a Result merkle tree type ResultTreeCID &ResultTreeNode</code></pre> <h2 id="tendermint-commit-and-commitsig" tabindex="-1"><a class="header-anchor" href="#tendermint-commit-and-commitsig">Tendermint Commit and CommitSig</a></h2> Commit is a simple wrapper for a list of commit signatures for every validator at a block, as well as the associated BlockID and corresponding block height and round. CommitSig represents a signature of a validator, who has voted either for nil, a particular BlockID, or was absent. It's a part of the Commit and can be used to reconstruct the vote set given the validator set. <pre class="language-ipldsch"><code class="language-ipldsch"># Commit contains the evidence that a block was committed by a set of validators # NOTE: Commit is empty for height 1, but never nil. type Commit struct { # NOTE: The signatures are in order of address to preserve the bonded # ValidatorSet order. # Any peer with a block can gossip signatures by index with a peer without # recalculating the active ValidatorSet. Height Int # Height at which this commit was created Round Int # Round that the commit corresponds to BlockID BlockID # The BlockID of the corresponding block Signatures Signatures # Array of CommitSigs for the validators at this block } # Signatures is a list of CommitSigs type Signatures [CommitSig] # CommitSig is a part of the Vote included in a Commit. type CommitSig struct { BlockIDFlag BlockIDFlag # Represents the validators participation in consensus: Either voted for the block that received the majority, voted for another block, voted nil or did not vote ValidatorAddress Address # Address of the validator Timestamp Time Signature Signature # Signature corresponding to the validators participation in consensus. }</code></pre> <h2 id="tendermint-commit-tree" tabindex="-1"><a class="header-anchor" href="#tendermint-commit-tree">Tendermint Commit Tree</a></h2> This is the IPLD schema for commit tree nodes. This is an alias for a <code>MerkleTreeNode</code> where the <code>Value</code> union type stored in a leaf node is a <code>CommitSig</code>. <ul> <li>The Commit Merkle Tree is Merkle tree built from the list of the previous block's commit signatures.</li> <li>The signatures represent the validators that committed to the last block.</li> <li>Leaves contain a protobuf serialized <code>CommitSig</code> object.</li> <li>CID links to a <code>CommitTreeNode</code> use an SHA256 multihash of the node binary and the TendermintCommitTree codec (tbd).</li> <li>The root node of this tree is referenced in a Tendermint <code>Header</code> by the <code>LastCommitCID</code>.</li> <li>The first block's Commit Merkle Tree is empty, and its root is represented as an empty byte slice.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch"># CommitTreeNode is an IPLD block for a node in a Commit Merkle Tree type CommitTreeNode MerkleTreeNode # CommitTreeCID is a CID link to a node in a Commit Merkle Tree type CommitTreeCID &CommitTreeNode</code></pre> <h2 id="tendermint-params" tabindex="-1"><a class="header-anchor" href="#tendermint-params">Tendermint Params</a></h2> HashedParams contains the max bytes and max gas for a block. <pre class="language-ipldsch"><code class="language-ipldsch"># HashedParamsCID is a CID link to the HashedParams for this Header # This CID is composed of the SHA256 multihash of the linked protobuf serialized HashedParams object and the TendermintParams codec (tbd) # HashedParams are referenced in a Tenderint Header by the ConsensusCID type HashParamsCID &HashedParams # HashedParams is a subset of ConsensusParams that is included in the consensus encoding # It is hashed into the Header.ConsensusHash type HashedParams struct { BlockMaxBytes Int BlockMaxGas Int }</code></pre> <h2 id="tendermint-proposal" tabindex="-1"><a class="header-anchor" href="#tendermint-proposal">Tendermint Proposal</a></h2> A CanonicalProposal contains the consensus fields used to propose a new block for validation. <pre><code># PropsalCID is a CID link to a CanonicalProposal for a block # This CID is composed of the SHA256 multihash of the linked protobuf serialized CanonicalProposal object and the TendermintProposal codec (tbd) type ProposalCID &Proposal # CanonicalProposal defines a block proposal for consensus. # It refers to the block by BlockID field. # It must be signed by the correct proposer for the given Height/Round # to be considered valid. It may depend on votes from a previous round, # a so-called Proof-of-Lock (POL) round, as noted in the POLRound. # If POLRound >= 0, then BlockID corresponds to the block that is locked in POLRound. type CanonicalProposal struct { SMType SignedMsgType Height Int Round Int # There can not be greater than 2_147_483_647 rounds POLRound Int # -1 if null. BlockID BlockID # The block being proposed Timestamp Time ChainID String } </code></pre> </div> </main> </body> </html>