github.com/aakash4dev/cometbft@v0.38.2/spec/README.md (about)

     1  ---
     2  order: 1
     3  title: Overview
     4  parent:
     5    title: Spec
     6    order: 7
     7  ---
     8  
     9  # CometBFT Spec
    10  
    11  This is a markdown specification of CometBFT.
    12  It defines the base data structures, how they are validated,
    13  and how they are communicated over the network.
    14  
    15  If you find discrepancies between the spec and the code that
    16  do not have an associated issue or pull request on github,
    17  please submit them to our [bug bounty](https://cometbft.com/security)!
    18  
    19  ## Contents
    20  
    21  - [Overview](#overview)
    22  
    23  ### Data Structures
    24  
    25  - [Encoding and Digests](./core/encoding.md)
    26  - [Blockchain](./core/data_structures.md)
    27  - [State](./core/state.md)
    28  
    29  ### Consensus Protocol
    30  
    31  - [Consensus Algorithm](./consensus/consensus.md)
    32  - [Creating a proposal](./consensus/creating-proposal.md)
    33  - [Time](./consensus/bft-time.md)
    34  - [Light-Client](./consensus/light-client/README.md)
    35  
    36  ### P2P and Network Protocols
    37  
    38  - [The Base P2P Layer](./p2p/legacy-docs/node.md): multiplex the protocols ("reactors") on authenticated and encrypted TCP connections
    39  - [Peer Exchange (PEX)](./p2p/legacy-docs/messages/pex.md): gossip known peer addresses so peers can find each other
    40  - [Block Sync](./p2p/legacy-docs/messages/block-sync.md): gossip blocks so peers can catch up quickly
    41  - [Consensus](./p2p/legacy-docs/messages/consensus.md): gossip votes and block parts so new blocks can be committed
    42  - [Mempool](./p2p/legacy-docs/messages/mempool.md): gossip transactions so they get included in blocks
    43  - [Evidence](./p2p/legacy-docs/messages/evidence.md): sending invalid evidence will stop the peer
    44  
    45  ### RPC
    46  
    47  - [RPC SPEC](./rpc/README.md): Specification of the CometBFT remote procedure call interface.
    48  
    49  ### Software
    50  
    51  - [ABCI](./abci/README.md): Details about interactions between the
    52    application and consensus engine over ABCI
    53  - [Write-Ahead Log](./consensus/wal.md): Details about how the consensus
    54    engine preserves data and recovers from crash failures
    55  
    56  ## Overview
    57  
    58  CometBFT provides Byzantine Fault Tolerant State Machine Replication using
    59  hash-linked batches of transactions. Such transaction batches are called "blocks".
    60  Hence, CometBFT defines a "blockchain".
    61  
    62  Each block in CometBFT has a unique index - its Height.
    63  Heights in the blockchain are monotonic.
    64  Each block is committed by a known set of weighted Validators.
    65  Membership and weighting within this validator set may change over time.
    66  CometBFT guarantees the safety and liveness of the blockchain
    67  as long as less than 1/3 of the total weight of the Validator set
    68  is malicious or faulty.
    69  
    70  A commit in CometBFT is a set of signed messages from more than 2/3 of
    71  the total weight of the current Validator set. Validators take turns proposing
    72  blocks and voting on them. Once enough votes are received, the block is considered
    73  committed. These votes are included in the _next_ block as proof that the previous block
    74  was committed - they cannot be included in the current block, as that block has already been
    75  created.
    76  
    77  Once a block is committed, it can be executed against an application.
    78  The application returns results for each of the transactions in the block.
    79  The application can also return changes to be made to the validator set,
    80  as well as a cryptographic digest of its latest state.
    81  
    82  CometBFT is designed to enable efficient verification and authentication
    83  of the latest state of the blockchain. To achieve this, it embeds
    84  cryptographic commitments to certain information in the block "header".
    85  This information includes the contents of the block (eg. the transactions),
    86  the validator set committing the block, as well as the various results returned by the application.
    87  Note, however, that block execution only occurs _after_ a block is committed.
    88  Thus, application results can only be included in the _next_ block.
    89  
    90  Also note that information like the transaction results and the validator set are never
    91  directly included in the block - only their cryptographic digests (Merkle roots) are.
    92  Hence, verification of a block requires a separate data structure to store this information.
    93  We call this the `State`. Block verification also requires access to the previous block.