tendermint-rs: Rust client libraries for Tendermint chains

One project for the client side of a Tendermint chain

Tendermint is a consensus engine for Byzantine fault tolerant applications written in any programming language, and the Go implementation has been the reference for years. tendermint-rs is the Rust answer to the question of what a non-Go team reaches for.

The scope is client libraries rather than a node. The crates cover the pieces an application needs to talk to a chain: data structures and serialization, an RPC client with its response types, protobuf wire types, a light client that verifies signed headers and tracks validator set changes, a detector for attacks against that light client, a p2p crate that currently provides connectivity to nodes over Tendermint's secret connection, and a low-level framework for building ABCI applications.

The list in the README is worth reading as a map of what the project believes belongs together. The tendermint crate holds the core data structures and their serialization. tendermint-proto holds the protobuf structures, generated using Prost. tendermint-rpc is the RPC client. tendermint-abci is described as a lightweight, low-level framework for building ABCI applications in Rust, which is the piece that lets you write an application that a Tendermint node can run.

The audience is therefore Rust engineers with a specific need: a chain that runs Tendermint or its successor, and an application that has to talk to it safely. It is not a general blockchain framework and it does not implement consensus.

The repository lives under the cometbft organisation, the description calls it client libraries for Tendermint and CometBFT in Rust, and the topic tags list cometbft, tendermint, light-client and rust. The licence is Apache 2.0, with the copyright held by Informal Systems and contributors.

The light client family and the detector that attacks it

Three crates deserve separate attention because they represent the security-critical part of the stack.

tendermint-light-client is the verification library. It verifies signed headers and tracks validator set changes, which is the minimum a non-full-node client has to do to know it is talking to the same chain and seeing the same validator set. tendermint-light-client-detector is described as a library for detecting and reporting attacks against the light client, and tendermint-light-client-cli is the command line counterpart, used for verifying headers, detecting attacks and reporting them.

The pairing of verifier and detector is the interesting design decision. A light client that cannot detect a bad header is a light client that trusts whoever feeds it headers, and an attack on a chain is often exactly an attempt to feed a client a header signed by the wrong validator set. Shipping the detector as a separate crate and a separate CLI means the check is available to anyone, not only to whoever maintains the verifier.

There is also tendermint-light-client-js, a low-level WASM interface for interacting with the light client verification functionality, which is how a browser or JavaScript runtime would run the same verification logic rather than trusting a server to do it.

The p2p crate completes the picture, and it is the one with the narrowest description: at present it primarily provides the ability to connect to Tendermint nodes via Tendermint's secret connection, the authenticated encryption handshake described in the Tendermint peer specification. That word primarily is doing real work, and it is a limit on what to expect from the crate.

Pre-1.0 versioning where MINOR means breaking

The versioning scheme deserves a paragraph of its own, because it will bite you at upgrade time if you assume the usual conventions.

The README states that the project does its best to follow Semantic Versioning, but that since it is pre-v1.0.0, the MINOR version refers to breaking changes and the PATCH version carries features, improvements and fixes. Under the usual rules of semver that mapping is inverted for a 0.x release, and the project is saying so plainly rather than leaving you to infer it.

The practical consequence is that a dependency bump from 0.40.3 to 0.40.4 is safe, while 0.40.x to 0.41.0 can break your build. If your Cargo.lock pins the exact patch, you will not notice this, and if you let a bot update minor versions you will. With a set of crates that share a version and are released collectively, a single update moves several dependencies at once.

The collective release policy is the other half. The README states that the same version is used for all crates and they are released together, so you never have to reconcile a light client version against an RPC version, and you also never get to take only the crates you need a fix for.

Release tags live on GitHub and the crates themselves are published on crates.io, with the badge and links in the README pointing at crates.io and docs.rs. The repository also carries a CHANGELOG.md, a .changelog/ directory, a release.sh script and a .codecov.yml configuration, which is the usual shape for a project with a scripted release process.

The TLA+ specifications shipped alongside the Rust code

Most client libraries document intent in prose. tendermint-rs does something different: the README states that this repository contains the TLA+ specifications and Rust implementations for various components of Tendermint, with the specifications living in the docs directory under a spec subdirectory.

TLA+ is a specification language used to describe concurrent and distributed algorithms formally, and the reference in the README links to a set of papers: the latest gossip on BFT consensus, and Ethan Buchman's master's thesis on Tendermint. That is the academic backbone of the engine, and having the specifications in the same repository as the implementations means the two can be read side by side.

For an adopter this has a specific use. If you are integrating a light client and need to reason about what it does when a peer sends it something inconsistent, the specification is the place to look, rather than reverse-engineering the Rust. The same applies to anyone evaluating the p2p secret connection implementation.

There is a governance detail in the README worth noting for contributors. The Tendermint protocols are specified in English in the tendermint/tendermint repository, and any protocol changes or clarifications should be contributed there, not here. This repository implements and specifies components, but the protocol itself is changed upstream. That split is worth remembering before you open a pull request that changes behaviour.

Adding the crates to a Rust project

There is no installation script here, because these are ordinary Rust crates published on crates.io, with API documentation on docs.rs. The README points to each component's documentation, and the badges in the project header link to the tendermint crate on crates.io and its documentation on docs.rs.

The repository itself is a Cargo workspace, and the workspace file shows exactly which crates ship together:

[workspace]
resolver = "2"

members = [
    "abci",
    "config",
    "light-client",
    "light-client-verifier",

The member list is the clearest description of the crate set you will find on crates.io, and it includes components the README summary does not mention, such as a light-client-verifier crate, a std-ext crate, and test and testgen crates used for testing and for generating test fixtures. The workspace also excludes proto-compiler and a tools/no-std-check directory, which indicates that the protobuf definitions are compiled by a separate tool and that there is a no_std build check for part of the tree.

The requirements section says the project is tested against the latest stable version of Rust and may work with older versions, and the header carries a Rust stable badge and a build status badge pointing at the Rust workflow. The repository also has an audit check workflow, which is worth noting for a project whose security value depends on cryptographic verification code.

So the first real use is the ordinary Rust one: add the crate you need as a dependency, read its documentation on docs.rs, and start from the type definitions. For a light client, expect to read the specification alongside the code.

Where tendermint-rs is the wrong tool

The first limit is the compatibility target. The README states that tendermint-rs has been tested for compatibility with Tendermint Core v0.34.21. That is a specific, narrow statement, and it is the one you should check against your chain. The project is now under the cometbft organisation and the description covers CometBFT, but the tested target named in the README is a Tendermint Core version, and the README does not say which CometBFT release the crates track. If your chain has moved to a protocol revision with different handshake or evidence rules, that gap is where you will find out.

The second limit is scope. The crate list contains no full node, no block execution engine and no consensus implementation. The p2p crate connects to nodes, but the description says primarily, and the light client verifies headers rather than tracking every block. If you need to serve a chain or replay history, this is the wrong library.

The third is the pre-1.0 versioning scheme, which is a genuine upgrade-cost issue for a project with many crates released in lockstep. A minor version bump can break the build across several dependencies simultaneously.

The fourth is the release cadence relative to today. The repository is not archived, but the last push was on 2026-04-17 and the newest release tag is v0.40.4 from 2025-05-05, with v0.40.3 and v0.40.2 in April 2025. A project whose published crates stopped moving in 2025 while the main branch kept receiving commits is fine to use and awkward to depend on for new work, because there is a gap between what is on crates.io and what is in the repository.

Editorial conclusion

Adopt tendermint-rs if you are writing a Rust client, relayer or light client for a Tendermint or CometBFT based chain and want the RPC, protobuf and verification layers to come from one project with published specifications. Do not adopt it as a consensus engine, a full node, or a drop-in for an arbitrary Cosmos SDK chain, since the crate set is a client surface and the compatibility target is Tendermint Core v0.34.21. Verify first that your chain speaks a protocol within that target, that you can accept a pre-1.0 versioning scheme where a MINOR bump means breaking changes, and that the crate versions you pin still receive fixes, since the last push was on 2026-04-17 and the newest release tag is v0.40.4 from 2025-05-05.

Frequently asked questions

Official sources

1. cometbft/tendermint-rs on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases