DOCSEARCHbyAlgolia
Submit Docs

CometBFT Documentation

repository·main·Indexed 21 days ago

https://github.com/cometbft/cometbft

CometBFT is a high-performance, Byzantine Fault Tolerant (BFT) consensus engine used for secure state machine replication in decentralized applications. It decouples the consensus and P2P layers from the application state via the Application BlockChain Interface (ABCI), allowing developers to write application logic in any programming language. The engine supports various cryptographic algorithms including Ed25519, secp256k1, BLS12-381, and ML-DSA-65.

Tokens
220.9K
Snippets
465
Records
923
Agent score
74%

What's inside CometBFT

  1. What is CometBFT

    main

    CometBFT is software designed for the secure and consistent replication of an application across multiple machines. It provides Byzantine Fault Tolerance (BFT), meaning the system remains functional and consistent as long as less than 1/3 of the machines fail or act maliciously (arbitrary behavior).

    CometBFT consists of two main components:

    1. Consensus Engine: Based on the Tendermint consensus algorithm, it ensures all machines record the same transactions in the same order.
    2. Application BlockChain Interface (ABCI): A generic interface that delivers transactions to applications for processing. This allows developers to write application logic in any programming language, decoupling the consensus and P2P layers from the application state.

  2. Overview of the CometBFT P2P layer implementation

    main

    The peer-to-peer (p2p) communication layer in CometBFT is organized into several key abstractions that handle connectivity, routing, and peer discovery. Developers building on or extending CometBFT should understand these core components:

    • Transport: Handles the establishment of secure and authenticated connections with remote peers.
    • Switch: Acts as the central routing hub. It is responsible for dialing new peers, accepting incoming connections, managing established connections, and routing messages between local 'reactors' and remote peers.
    • PEX (Peer Exchange) Reactor: A multi-faceted component responsible for peer discovery and management, consisting of:
      • Peer Exchange protocol: The mechanism used to exchange peer addresses for discovery.
      • Address Book: A storage layer for discovered peer addresses and quality metrics for peers the node has interacted with.
      • Peer Manager: The logic that determines when and which peers the node should dial to establish outbound connections.
    • Types: The foundational data structures and parameters used throughout the p2p package.

  3. Overview of Ivy Proofs specifications

    main

    The spec/ivy-proofs/ directory contains formal specifications and proofs of the Tendermint algorithm written in Ivy. The files include:

    • tendermint.ivy: The specification of the Tendermint algorithm.
    • abstract_tendermint.ivy: A more abstract, verification-friendly version of the specification.
    • classic_safety.ivy: Proof of the classic BFT safety property (no two well-behaved nodes disagree if quorums overlap with a well-behaved node).
    • accountable_safety_1.ivy: Proof that if well-behaved nodes disagree, evidence exists of at least $f+1$ misbehaving nodes (assuming quorums contain at least one well-behaved node).
    • accountable_safety_2.ivy: Proof that well-behaved nodes cannot be framed by malicious nodes.
    • network_shim.ivy: The network model and a shim object for interfacing with the specification.
    • domain_model.ivy: The underlying domain model (rounds, values, quorums, etc.).

  4. Review Tendermint Core QA Results for v0.37.x

    main
    This report summarizes the Quality Assurance (QA) testing performed on CometBFT (formerly Tendermint Core) version 0.37.x. The testing focused on a 200-node testnet to identify the saturation point, examine latencies, and monitor Prometheus metrics under load. The results for v0.37.x were found to be largely consistent with the v0.34.x baseline, with the test passing.

  5. Understand Rotating Node Testnet performance results

    main

    The Rotating Node Testnet evaluates CometBFT performance under a safe workload using c=1,r=400 load parameters. This testnet configuration typically consists of 10 validators and 25 full nodes.

    Key performance observations for v0.38.0-alpha.2 compared to the v0.37.0-alpha.2 (Tendermint Core) baseline include:

    • Latencies: Average latency increases by approximately 1 second compared to the baseline. This is attributed to higher transaction throughput, as the baseline was affected by issue [#9539] which caused CheckTx to reject most transactions.
    • Transaction Throughput: The rate of transactions processed per minute is significantly higher in the rotating testnet than in the baseline due to the fix for [#9539].
    • Memory Usage: The average Resident Set Size (RSS) is notably larger in v0.38.0-alpha.2 because the system is processing a higher volume of transactions.
    • CPU Utilization: CPU load (measured via load1) remains generally under 5, which is considered normal, though slightly higher on average due to increased transaction processing.

  6. CometBFT RPC Protocol Support

    main

    CometBFT implements the JSON-RPC 2.0 specification. The RPC layer supports multiple transport protocols and provides a wide range of routes for interacting with the blockchain state, consensus, and ABCI.

    Supported transports:

    • HTTP/HTTPS: Standard web protocols.
    • WS (WebSockets): For real-time communication.
    • JSON-RPC 2.0: The core messaging format.

  7. Browse CometBFT P2P component messages

    main

    CometBFT P2P messages are categorized by the component they serve. You can find detailed specifications for each component's messaging protocol in the following sections:

    • Block Sync: Messages related to catching up on blocks.
    • Mempool: Messages for transaction propagation and mempool management.
    • Evidence: Messages for communicating validator evidence.
    • State Sync: Messages for rapid state synchronization.
    • Pex (Peer Exchange): Messages for peer discovery and network topology management.
    • Consensus: Messages required for the consensus engine to operate.

  8. Understand the CometBFT Consensus Protocol

    main

    CometBFT implements a Byzantine Fault Tolerant (BFT) consensus algorithm based on the Tendermint protocol. The consensus engine ensures safety and termination in the presence of Byzantine (malicious) actors.

    Key components of the consensus specification include:

    • Consensus Algorithm: Detailed in the Consensus Paper.
    • BFT Time: Mechanisms for computing timestamps in block headers in a BFT manner.
    • Proposals: The process by which a proposer creates a block proposal.
    • Light Client Protocol: A protocol designed for lightweight consensus verification and syncing to the latest state.
    • Validator Signing: Cryptographic signature rules for validators.
    • Write Ahead Log (WAL): A mechanism used by the consensus state machine to recover from crashes.

  9. Onboarding Projects for New Engineers

    main

    This document outlines potential projects for new engineers joining the CometBFT (formerly Tendermint) team. These projects are designed to provide exposure to different areas of the codebase, require moderate context, and strike a balance between trivial tasks and large, intractable changes.

    Key areas for exploration include:

    • E2E Test Systems: Working with the end-to-end framework, generators, and runners.
    • Error Handling: Converting panics into proper error returns (refer to rfc-008-do-not-panic.md).
    • ABCI Applications: Implementing more expressive applications to mirror downstream user experiences.
    • Metrics & Logging: Improving the utility of the metrics system and converting verbose logs into actionable metrics.
    • Core Logic: Exploring reactor semantics (e.g., making them pauseable) and P2P layer improvements.

  10. Identify core P2P layer types and packages

    main

    The CometBFT P2P layer is organized into several specialized packages. When building or extending the P2P layer, you will interact with these primary components:

    • p2p: The main implementation of the P2P layer, containing the Switch, Transport, and Reactor logic.
    • p2p.conn: Handles encrypted, authenticated, and multiplexed connections between nodes.
    • p2p.pex: Implements the Peer Exchange (PEX) reactor, managing the address book and outbound peer discovery.
    • p2p.mock / p2p.mocks: Provides mock implementations of Peer and Reactor for testing.
    • p2p.trust: Contains the Metric type used to track peer reliability.

  11. Explore CometBFT Core functionality

    main

    The Core section of the CometBFT documentation provides the foundational technical specifications for the protocol implementation. Developers building on top of CometBFT should consult these specific areas to understand the underlying mechanics:

    • Core Data Structures: Definitions of the fundamental types used throughout the protocol.
    • Encoding: Specifications for how data is serialized and represented.
    • Genesis: Details on the genesis state and how the network initializes.
    • State: Information regarding the protocol's state machine and state management.

  12. Explore CometBFT Blockchain core types and functionality

    main

    The Blockchain section of the CometBFT documentation provides a high-level overview of the protocol's implementation. It is organized into three primary areas of concern for developers building on or with the protocol:

    • Core Data Structures: Details the fundamental types used throughout the protocol.
    • Encoding: Explains how data is serialized and represented.
    • State: Describes how the blockchain state is managed and maintained.