1 unstable release
0.1.0-alpha.2 | Jan 27, 2024 |
---|
#3 in #cometbft
Used in 2 crates
1.5MB
25K
SLoC
See the repo root for build status, license, rust version, etc.
Light-Client
Implementation of the Light Client Verification and [Attack Detection][light-client-detection] protocols.
Documentation
See documentation on docs.rs.
Testing
The CometBFT Light Client is primarily tested through unit tests.
Core Verification
The logic for the core verification of light blocks is entirely self-contained in
the predicates
module.
This code is exercised through unit tests which test each predicate in isolation
by giving it a set of data along with the expected outcome of each check.
The following command can be used to run only these tests:
cargo test -p cometbft-light-client predicates
Model-based tests
We started to employ model-based testing (MBT), which is currently limited to the core verification. In MBT, the testing procedure is based on the Light Client formal model, and the tests themselves are simple assertions in the modeling language TLA+. The current set of TLA+ tests is translated automatically into the set of JSON fixtures.
The following command can be used to run only these tests:
$ cargo test -p cometbft-light-client --test model_based -- --nocapture
Please refer to the MBT Guide, and the MBT Abstract for further information.
Bisection
Similarly to the core verification logic, the algorithm for performing bisecting verification is exercised via a set of JSON fixtures which encode an initial trusted state, a target block to verify, a set of intermediary blocks, and the expected result of the bisection algorithm.
These tests target the light_client
module,
and can be found in the tests/light_client.rs
file.
To run the tests:
$ cargo test -p cometbft-light-client --test light_client bisection
Attack Detection
Please see the light-client-detector
crate.
Voting Power Calculator
The voting power calculator is exercised through unit tests which rely on JSON fixtures to provide the calculator with various types of light blocks together with the expected result of the computation.
The following command can be used to run only these tests:
$ cargo test -p cometbft-light-client voting_power
Integration Tests
This project also includes simple integration test which spawns a light client instance against a single CometBFT full node which acts both as a primary peer and as its own witness.
Because this test requires a running CometBFT node, it is ignored by default. To run this test locally:
# In one terminal
$ mkdir -p /tmp/cometbft
$ docker run -it --rm -v "/tmp/cometbft:/cometbft" cometbft/cometbft init
$ docker run -it --rm -v "/tmp/cometbft:/cometbft" -p 26657:26657 cometbft/cometbft node --proxy_app=kvstore
# In another terminal
$ cargo test -p cometbft-light-client --test integration -- --ignored --nocapture
Other tests
A few core datastructures, such as the PeerList
implementation,
come with unit tests located in the same module as the implementation.
To run these tests together with all tests described above:
$ cargo test -p cometbft-light-client --all-features
Dependencies
~11–28MB
~422K SLoC