Tendermint/CometBFT Consensus: Implementation and Optimization

Tendermint (today branded as CometBFT’s consensus engine) is the part of the Cosmos stack that actually decides which block comes next. Once you understand how its rounds, votes, and timeouts interact, you can reason clearly about safety, finality, and how far you can push throughput before the system starts to creak.

In this article I’ll walk through the Tendermint BFT protocol in practical terms: validator sets and voting power, the Propose → Prevote → Precommit dance, why finality is instant once a block is committed, and how I approach performance tuning for high‑throughput chains.

1. System model and validator sets

Tendermint assumes a partially synchronous network and a fixed validator set at each height. The core BFT assumption is the classic:

n = 3f + 1 validators
tolerate up to f Byzantine faults
quorum (supermajority) = 2f + 1 voting power

In CometBFT’s docs this is phrased as “works as long as less than 1/3 of machines fail in arbitrary ways,” and all correctness proofs are written under that assumption.(CometBFT Documentation)

Validators are identified by keys and voting power. Voting power is usually proportional to stake in proof‑of‑stake systems, but the consensus algorithm itself only sees integer weights and supermajority thresholds. The Tendermint docs emphasise that validators broadcast signed votes and may have different voting power; we always talk about “2/3 of voting power”, not “2/3 of node count”.(Tendermint Core Documentation)

At any given height, exactly one block will be committed, or none if consensus stalls. The protocol repeats per height.

2. Heights, rounds, and steps

For each block height H, Tendermint runs a round‑based protocol. Each round tries to commit a block for height H.

I like to picture it like this:

height H:

  NewHeight
    |
    v
  round 0:
    Propose -> Prevote -> Precommit
    |           |            |
    |           |            +-- if +2/3 precommits for block B -> Commit B
    |           +-- if timeout / nil / no agreement -> next round
    +-- if proposer missing / invalid block     -> next round

  round 1:
    Propose -> Prevote -> Precommit
    ...

The CometBFT consensus spec writes the “ideal path” as:

NewHeight -> (Propose -> Prevote -> Precommit)+ -> Commit -> NewHeight -> ...

(CometBFT Documentation)

If anything goes wrong in a round — offline proposer, invalid block, network delay, or not enough votes — validators move to the next round with a new proposer. Timeouts increase with the round number to give the network more slack.(CometBFT Documentation)

3. Propose, prevote, precommit

Each round has three main steps plus the special Commit step.

Propose. A single proposer, chosen deterministically in proportion to voting power, gossips a block proposal for height H, round R. The proposal includes the block and, optionally, a proof‑of‑lock (PoLC) from a previous round to help locked validators move forward.(CometBFT Documentation)

If validators do not receive a valid proposal before timeoutPropose, they move on and will tend to vote nil in this round.

Prevote. Once in Prevote, each validator broadcasts a prevote:

• If it is already locked on some block, it prevotes for that locked block.
• Otherwise, if it has received a valid proposal for this round, it prevotes for that proposal.
• Otherwise, it prevotes <nil>.(CometBFT Documentation)

The step ends when someone observes more than 2/3 of voting power in prevotes for some block B or for <nil>, or when timeoutPrevote expires. A 2/3 prevote set for a block is sometimes nicknamed a polka in the documentation.(CometBFT Documentation)

Precommit. In Precommit, validators use the polka to update their locks and broadcast precommits:

• If there is a polka for block B in this round, they lock on B and precommit B.
• If there is a polka for <nil>, they unlock and precommit <nil>.
• Otherwise, they keep whatever lock they had and precommit <nil>.(CometBFT Documentation)

The precommit step ends similarly: on 2/3 precommits for some block or <nil>, or on timeout. If any validator sees more than 2/3 precommits for a block B in the same (H, R), it commits B for height H.

The state machine diagram from the spec matches this flow exactly; the arrows from Prevote to Precommit, and from Precommit either to Commit or back to Propose of a higher round, encode all those conditions.(CometBFT Documentation)

4. Locking rules and safety

The “magic” that prevents forks is the locking discipline.

Once a validator precommits a block at (H, R), it is considered locked on that block. The CometBFT docs summarise the rules as:

1. A locked validator must prevote for the block it is locked on.
2. It may only unlock and precommit a new block if there is a polka for that new block in a later round.

(CometBFT Documentation)

Intuition in short paragraphs:

If a block B ever gets 2/3 precommits in round R, at least 1/3 of voting power is honest and locked on B at round ≥ R. Those honest locked validators will not switch to a different block at the same or lower round, because they only unlock for a strictly later‑round polka. That means you cannot get another block C to 2/3 precommits at the same height, unless 1/3 of voting power outright violates the protocol (double signing).

The consensus spec formally proves that, under the “< 1/3 Byzantine voting power” assumption, no two correct validators can commit different blocks at the same height. Any fork necessarily implies at least 1/3 misbehaving validators, which then become slashable via double‑signing evidence in PoS systems.(CometBFT Documentation)

5. Instant finality and what it really means

Tendermint provides instant finality in the following precise sense:

Once a block has more than 2/3 precommits from the current validator set,
no other conflicting block at that height can ever be committed unless
at least 1/3 of voting power violates the protocol.

So from a full node’s perspective, once it has seen the 2/3 precommit set and applied the block, that block is final (Subjective Commit). The canonical chain pins this down by including the commit hash for the previous block in each new block’s header (Canonical Commit).(CometBFT Documentation)

Light clients rely on the same guarantee but only need to track headers and commit signatures, sometimes with extra accountability logic to detect equivocation or lunatic validators. The fork‑accountability spec builds on this: if there are two conflicting commits at the same height, you can always extract at least 1/3 of voting power that double‑signed or otherwise misbehaved.(CometBFT Documentation)

Finality here is cryptographic + protocol‑level, not probabilistic like Bitcoin’s “6 confirmations” rule. There is no notion of “reorg depth” under the usual BFT assumption; either all honest nodes agree on the block, or <2/3 of voting power has participated.

6. Liveness, timeouts, and eventual synchrony

Safety is clear; liveness is more subtle.

Tendermint assumes the network is eventually synchronous: there may be arbitrary delays for some time, but eventually message delays are bounded. Under this assumption, and with <1/3 Byzantine voting power, the protocol’s timeout and proposer rotation logic guarantee that a new block is eventually committed.(CometBFT Documentation)

Timeouts are per round and per step. The spec talks about parameters like:

timeoutProposeR, timeoutPrevote, timeoutPrecommit, timeoutCommit

which can grow round by round if needed. If the proposer is offline or its block doesn’t propagate in time, validators see missing or invalid proposals, prevote <nil>, and quickly move to the next round with a new proposer. If the network is simply slow, timeouts increase until proposals and votes can fully gossip before expiring.(CometBFT Documentation)

This is where the performance vs liveness trade‑off lives: aggressive timeouts give low latency in healthy conditions but risk spurious round failures under load or jitter. Conservative timeouts hurt latency but make the system robust to unstable networks.

From the trenches: I treat Tendermint’s timeout config like TCP congestion control: start with conservative defaults, observe behaviour under realistic latency and jitter, and only then dial down. Trying to force “sub‑second blocks” on a wide‑area network with 100+ validators usually ends in a flurry of extra rounds and worse throughput.

7. Validator sets and changes over time

At a fixed height, Tendermint assumes a fixed validator set. But real chains need to add, remove, or reweight validators.

The canonical pattern (used by Cosmos chains) is:

- The application (Cosmos SDK) computes validator updates in EndBlock.
- Those updates are included in block H.
- CometBFT applies them before running consensus for height H+1.

Tendermint’s validator docs explain that nodes can be in the initial genesis validator set or added later via EndBlock updates from the ABCI app. Voting power is attached to keys, and consensus only considers the active validator set at each height.(Tendermint Core Documentation)

If you combine this with slashing (implemented in the application), you get a complete staking story: misbehaviour in the consensus layer is detected through evidence (double‑signing, lunatic behaviour) and punished economically by the state machine.(CometBFT Documentation)

8. Where performance actually comes from

On paper Tendermint consensus is “just” a few message rounds. In production, throughput is shaped by a handful of subsystems:

- Consensus parameters: timeouts, block size, votes
- Mempool and ABCI latency
- Network topology and p2p throttling
- Node hardware and disk I/O (WAL, DB)

The core algorithm doesn’t change; you’re tuning the environment so that proposal + two voting stages + commit can happen smoothly within your chosen block time.

8.1 Consensus parameters

Most operators touch three families of settings in config.toml:

- Block size and gas:
    how many txs fit in a block, and how much execution work is allowed.

- Consensus timeouts:
    timeout_propose, timeout_prevote, timeout_precommit, timeout_commit
    and their per-round deltas.

- Commit behaviour:
    whether to skip the full commit timeout if all votes arrive early.

Recent Tendermint/CometBFT versions even added “unsafe overrides” for timeouts, with strong warnings; they are meant as temporary escape hatches because wrong values can break liveness.(Tendermint Core Documentation)

There is a clear pattern: you pick a target block time, then choose timeouts that give the proposer enough time to gather a full block and for votes to gossip, in the worst case for your network.

If you undershoot, you see frequent rounds with <nil> votes, more skipped proposers, and effective throughput collapses. If you overshoot, the chain “feels slow” even though consensus would be capable of faster commits.

8.2 Mempool and ABCI

The mempool is an ordered in‑memory queue of transactions. Its job is to:

- Accept new txs, run CheckTx over ABCI to validate them.
- Keep them in an efficient concurrent structure (CListMempool).
- Let the proposer reap a batch that fits maxBytes / maxGas.

Recent implementations describe CListMempool as an ordered, concurrent list with limits on count and total bytes, plus an LRU cache to avoid re‑checking duplicate txs.(Go Packages)

Two practical knobs matter most for throughput:

The mempool.recheck flag controls whether every remaining transaction is revalidated after each block. The production docs explicitly suggest turning it off if your ABCI app doesn’t need that (for example, if validity only depends on simple stateless checks and a nonce).(Tendermint Core Documentation)

The mempool.broadcast flag controls whether transactions are relayed to peers before being included in a block. Turning it off reduces gossip overhead but can concentrate load on a few nodes.(Tendermint Core Documentation)

Real throughput depends heavily on ABCI latency: how long your application takes to run CheckTx and DeliverTx. CometBFT can push transactions fast, but if your state machine or database is slow, block production backs up regardless of how tight your consensus timeouts are.

8.3 Network and I/O

The “Running in production” guide calls out a few obvious but important points:

• Use SSDs; consensus and mempool both use write‑ahead logs that can become I/O bound on poor disks.
• Tune P2P send_rate, recv_rate, flush_throttle_timeout, and packet size if you have a dedicated high‑speed network.
• For public networks, validate hardware and OS, and avoid 32‑bit architectures for validator keys due to constant‑time crypto concerns.(Tendermint Core Documentation)

On top of this, the validator count and geography matter. Each block’s commit includes a vote from each validator; with many validators the commit structure gets larger, and each extra millisecond of network latency eats into your timeout budget. Informal testing and forum discussions around Tendermint have shown that naive configurations with 100+ validators and 1k tx/s on commodity cloud machines can easily push block times into the tens of seconds if parameters and hardware are not tuned together.(Cosmos Hub Forum)

From the trenches: on a high‑traffic Cosmos‑SDK‑based chain we cut block times in half just by (a) raising send_rate/recv_rate on validator P2P links, (b) disabling mempool recheck for a stateless fee market, and © giving the app a faster Postgres instance. The consensus algorithm itself didn’t change; we just stopped starving it.

9. An optimisation playbook for high‑throughput chains

When I design or tune a high‑throughput Tendermint chain, my mental checklist is:

First, choose realistic block time and validator count given network geography. A 1‑second block target with 150 globally distributed validators is not realistic; 3–6 seconds with 50–100 validators is usually more attainable without heroics.

Second, benchmark the application in isolation. Measure CheckTx and DeliverTx latency under realistic transaction mixes. If your app can’t process 2k tx/s on a single node, consensus won’t fix that.

Third, size block limits so that a full block’s worth of DeliverTx calls finishes comfortably within your proposed block time and hardware. It is better to commit smaller blocks reliably than to aim for monster blocks that constantly overrun timeouts.

Fourth, tune consensus timeouts starting from defaults. Verify that in healthy conditions most heights commit in round 0, with time to spare before timeoutCommit. Only then tighten them if you need lower latency.

Fifth, watch mempool metrics: queue size, recheck rate, ABCI errors, WAL size. If your mempool is constantly full, you’re saturating consensus or the app. If it’s empty, the bottleneck is upstream (clients, gateways).

Sixth, keep an eye on gossip lag. Tools that measure how long it takes votes and proposals to reach all validators are extremely helpful. CometBFT’s gossip property means a node can help others catch up by forwarding votes and parts of blocks, but bad peer topology can still create islands.(CometBFT Documentation)

Conclusion

Tendermint consensus is conceptually simple:

• Validators with weighted voting power run a round‑based protocol per height.
• Each round has a Propose → Prevote → Precommit sequence.
• Careful locking rules ensure that once 2/3 precommit a block, no conflicting block can be committed without 1/3 of voting power cheating.
• Under eventual synchrony, timeouts and proposer rotation guarantee progress.

From there, performance is a systems engineering problem: aligning consensus timeouts, mempool behaviour, ABCI latency, hardware, and network topology so that proposals and two voting rounds fit reliably inside your target block time.

Once you understand the state machine in terms of heights, rounds, steps, and locks, Tendermint stops being a black box. You can look at logs, mempool graphs, and config files and see exactly why a chain is fast, slow, or stuck — and what to change to push it toward the throughput and latency profile you need.

Completion scope and production contract

This completion review turns the earlier conceptual treatment into a release-oriented engineering contract. It treats Tendermint/CometBFT Consensus: Implementation and Optimization as a Cosmos SDK, CometBFT, or IBC component, follows a consensus round, ABCI request, SDK message, state-store write, or IBC packet through validation and durable state, and separates normative requirements from implementation policy. The normative baseline is the CometBFT consensus specification, Cosmos SDK interfaces, and applicable IBC standards; deployment defaults, caching, retry limits, and operator thresholds are explicitly local policy. 9

The intended audience is experienced developers and architects. Readers should understand the surrounding chain or application model, typed data structures, persistence, and basic security engineering. The scope includes correctness, implementation boundaries, deterministic tests, failure recovery, security, performance, and observability. It does not claim that the educational companion is a drop-in replacement for a maintained protocol or cryptographic library. Production adoption requires an independent threat model, compatibility testing against the authoritative implementation, and operational ownership. 10

The mental model used throughout is deliberately strict: untrusted input crosses consensus, ABCI, module keeper, store, gRPC, and relayer boundaries; a validator derives facts under the CometBFT consensus specification, Cosmos SDK interfaces, and applicable IBC standards; accepted transitions update versioned application state, validator state, consensus round, and light-client state; and observers consume committed facts, never optimistic intermediate mutations. A guarantee is stated only when it follows from those rules and assumptions. Heuristics such as fee selection, caching, peer scoring, timeouts, user messaging, or alert thresholds remain policy and may be tuned without redefining validity. 11

Reader contract and scope

For Tendermint/CometBFT Consensus: Implementation and Optimization, this review makes the exact user decision and the prerequisites needed to make it safely explicit. Start from one consensus round, ABCI request, SDK message, state-store write, or IBC packet and write down its origin, canonical representation, validation context, authority, and durable outcome. The Cosmos SDK, CometBFT, or IBC component must not infer a stronger fact from transport success, cache presence, or an upstream acknowledgement. Its authoritative state is versioned application state, validator state, consensus round, and light-client state, and every projection must remain rebuildable or reconcilable from committed facts. This framing distinguishes a protocol guarantee from an operational convenience and gives reviewers a concrete place to challenge an assumption. 9

The principal failure to design against is an attractive example being mistaken for a complete production design. Address it before optimizing by defining a narrow ownership boundary, stable identities, bounded resource use, and a machine-readable outcome for every rejected transition. Record a scope statement, excluded concerns, and a reviewable acceptance criterion. A reviewer should be able to trace each accepted result to input bytes, rule or policy version, prior state, and commit identity without relying on prose logs. When the authority cannot be reached or context is incomplete, return an explicit unavailable or pending state; do not convert uncertainty into acceptance.

Precise vocabulary and authority

Treat precise vocabulary and authority as part of the executable design of Tendermint/CometBFT Consensus: Implementation and Optimization, not as documentation added after coding. The relevant operating envelope includes proposal rounds, block execution, validator changes, packet relaying, upgrades, and state synchronization. For each mode, identify which state is authoritative, which work may be retried, what is bounded, and which observation proves progress. This is especially important across consensus, ABCI, module keeper, store, gRPC, and relayer boundaries, where delivery and processing are different events and where local time or arrival order may not reflect authoritative order. 10

A useful review asks how the design behaves under invalid vote, non-deterministic execution, timeout, client expiry, packet replay, store corruption, and version skew. The unsafe outcome is teams using the same word for incompatible states or guarantees. Prevent it with explicit preconditions and postconditions, and retain a glossary tied to the normative authority for every overloaded term as release evidence. Use stable codes rather than exception text, keep policy configuration versioned, and attach the accepted policy or rule version to durable results. An chain, validator, or relayer operator must be able to stop intake, drain or quarantine work, compare local state with authority, and resume without inventing a second side effect.

Trust assumptions

The implementation of Tendermint/CometBFT Consensus: Implementation and Optimization should expose which actors, clocks, stores, libraries, and upstream systems may fail or act maliciously through types and module boundaries. Parse external representations once, preserve the original identity when audit or replay needs it, and pass validated domain values inward. Mutations of versioned application state, validator state, consensus round, and light-client state belong behind one authoritative transition function or transaction boundary. Network clients, storage adapters, user interfaces, and telemetry exporters must not duplicate consensus or business rules. That separation keeps deterministic logic testable and prevents a library upgrade from silently redefining validity. 11

Assume that an implicit trusted component invalidating the claimed guarantee will eventually occur in a staging fault test or production incident. The control is not a catch-all retry: classify the outcome, decide whether the identical operation is safe to repeat, bound attempts and elapsed time, and surface terminal work for reconciliation. The minimum evidence is a trust-boundary diagram and an assumption register with owners. Keep validator keys, consensus evidence, capabilities, packet commitments, and untrusted protobuf messages out of ordinary logs, and prefer hashes, version identifiers, counts, and sanitized reason codes. Any emergency bypass must be narrow, time-limited, approved, and observable.

Architecture and ownership

Verification for Tendermint/CometBFT Consensus: Implementation and Optimization must demonstrate component responsibilities and the direction in which facts and commands move at several layers. Small tests cover deterministic transforms and boundary values; contract tests pin serialized forms; integration tests exercise real adapters; replay tests compare state roots or projections; and fault tests interrupt work at every commit boundary. The dataset must include normal history, malformed input, duplicates, reordering, maximum-size values, and changes of rule or schema version. A passing example is evidence about that environment and dataset, not a universal performance claim. 9

Make two components both believing they own the same transition a named negative test. The release packet should retain a context diagram, ownership table, and dependency rule, exact dependency and tool versions, the deterministic command, and its result. For performance work, report warm-up, repetitions, concurrency, percentiles, resource limits, and the point where backpressure begins. For security work, include abuse cases and independent review. A change is ready only when failures leave versioned application state, validator state, consensus round, and light-client state safe, recovery is rehearsed, and telemetry explains both user-visible outcome and operator action.

Canonical representation

For Tendermint/CometBFT Consensus: Implementation and Optimization, this review makes the byte-level or schema-level representation used for hashing, comparison, storage, and transport explicit. Start from one consensus round, ABCI request, SDK message, state-store write, or IBC packet and write down its origin, canonical representation, validation context, authority, and durable outcome. The Cosmos SDK, CometBFT, or IBC component must not infer a stronger fact from transport success, cache presence, or an upstream acknowledgement. Its authoritative state is versioned application state, validator state, consensus round, and light-client state, and every projection must remain rebuildable or reconcilable from committed facts. This framing distinguishes a protocol guarantee from an operational convenience and gives reviewers a concrete place to challenge an assumption. 10

The principal failure to design against is semantically equal values producing different identifiers or verification outcomes. Address it before optimizing by defining a narrow ownership boundary, stable identities, bounded resource use, and a machine-readable outcome for every rejected transition. Record golden encodings, round-trip tests, and rejection of non-canonical forms. A reviewer should be able to trace each accepted result to input bytes, rule or policy version, prior state, and commit identity without relying on prose logs. When the authority cannot be reached or context is incomplete, return an explicit unavailable or pending state; do not convert uncertainty into acceptance.

State-machine model

Treat state-machine model as part of the executable design of Tendermint/CometBFT Consensus: Implementation and Optimization, not as documentation added after coding. The relevant operating envelope includes proposal rounds, block execution, validator changes, packet relaying, upgrades, and state synchronization. For each mode, identify which state is authoritative, which work may be retried, what is bounded, and which observation proves progress. This is especially important across consensus, ABCI, module keeper, store, gRPC, and relayer boundaries, where delivery and processing are different events and where local time or arrival order may not reflect authoritative order. 11

A useful review asks how the design behaves under invalid vote, non-deterministic execution, timeout, client expiry, packet replay, store corruption, and version skew. The unsafe outcome is an impossible intermediate state becoming durable after interruption. Prevent it with explicit preconditions and postconditions, and retain a transition table exercised by positive, negative, and replay tests as release evidence. Use stable codes rather than exception text, keep policy configuration versioned, and attach the accepted policy or rule version to durable results. An chain, validator, or relayer operator must be able to stop intake, drain or quarantine work, compare local state with authority, and resume without inventing a second side effect.

Invariants

The implementation of Tendermint/CometBFT Consensus: Implementation and Optimization should expose properties that must hold before and after every accepted operation through types and module boundaries. Parse external representations once, preserve the original identity when audit or replay needs it, and pass validated domain values inward. Mutations of versioned application state, validator state, consensus round, and light-client state belong behind one authoritative transition function or transaction boundary. Network clients, storage adapters, user interfaces, and telemetry exporters must not duplicate consensus or business rules. That separation keeps deterministic logic testable and prevents a library upgrade from silently redefining validity. 9

Assume that local success concealing corruption in a related aggregate or index will eventually occur in a staging fault test or production incident. The control is not a catch-all retry: classify the outcome, decide whether the identical operation is safe to repeat, bound attempts and elapsed time, and surface terminal work for reconciliation. The minimum evidence is executable assertions at the narrowest authoritative boundary. Keep validator keys, consensus evidence, capabilities, packet commitments, and untrusted protobuf messages out of ordinary logs, and prefer hashes, version identifiers, counts, and sanitized reason codes. Any emergency bypass must be narrow, time-limited, approved, and observable.

Validation pipeline

Verification for Tendermint/CometBFT Consensus: Implementation and Optimization must demonstrate cheap structural checks, contextual checks, authoritative verification, and commit order at several layers. Small tests cover deterministic transforms and boundary values; contract tests pin serialized forms; integration tests exercise real adapters; replay tests compare state roots or projections; and fault tests interrupt work at every commit boundary. The dataset must include normal history, malformed input, duplicates, reordering, maximum-size values, and changes of rule or schema version. A passing example is evidence about that environment and dataset, not a universal performance claim. 10

Make expensive or stateful work running before malformed input is rejected a named negative test. The release packet should retain ordered validation stages with stable machine-readable rejection codes, exact dependency and tool versions, the deterministic command, and its result. For performance work, report warm-up, repetitions, concurrency, percentiles, resource limits, and the point where backpressure begins. For security work, include abuse cases and independent review. A change is ready only when failures leave versioned application state, validator state, consensus round, and light-client state safe, recovery is rehearsed, and telemetry explains both user-visible outcome and operator action.

Error semantics

For Tendermint/CometBFT Consensus: Implementation and Optimization, this review makes the distinction between invalid input, conflict, unavailable dependency, retryable interruption, and internal defect explicit. Start from one consensus round, ABCI request, SDK message, state-store write, or IBC packet and write down its origin, canonical representation, validation context, authority, and durable outcome. The Cosmos SDK, CometBFT, or IBC component must not infer a stronger fact from transport success, cache presence, or an upstream acknowledgement. Its authoritative state is versioned application state, validator state, consensus round, and light-client state, and every projection must remain rebuildable or reconcilable from committed facts. This framing distinguishes a protocol guarantee from an operational convenience and gives reviewers a concrete place to challenge an assumption. 11

The principal failure to design against is blind retries amplifying a permanent failure or changing user intent. Address it before optimizing by defining a narrow ownership boundary, stable identities, bounded resource use, and a machine-readable outcome for every rejected transition. Record typed errors mapped consistently across logs, metrics, APIs, and queues. A reviewer should be able to trace each accepted result to input bytes, rule or policy version, prior state, and commit identity without relying on prose logs. When the authority cannot be reached or context is incomplete, return an explicit unavailable or pending state; do not convert uncertainty into acceptance.

Concurrency control

Treat concurrency control as part of the executable design of Tendermint/CometBFT Consensus: Implementation and Optimization, not as documentation added after coding. The relevant operating envelope includes proposal rounds, block execution, validator changes, packet relaying, upgrades, and state synchronization. For each mode, identify which state is authoritative, which work may be retried, what is bounded, and which observation proves progress. This is especially important across consensus, ABCI, module keeper, store, gRPC, and relayer boundaries, where delivery and processing are different events and where local time or arrival order may not reflect authoritative order. 9

A useful review asks how the design behaves under invalid vote, non-deterministic execution, timeout, client expiry, packet replay, store corruption, and version skew. The unsafe outcome is a check-then-act race accepting two individually plausible operations. Prevent it with explicit preconditions and postconditions, and retain a linearization argument plus stress tests at the chosen contention boundary as release evidence. Use stable codes rather than exception text, keep policy configuration versioned, and attach the accepted policy or rule version to durable results. An chain, validator, or relayer operator must be able to stop intake, drain or quarantine work, compare local state with authority, and resume without inventing a second side effect.

References