github.com/aakash4dev/cometbft@v0.38.2/spec/light-client/README.md (about) 1 --- 2 order: 1 3 parent: 4 title: Light Client 5 order: 5 6 --- 7 8 # Light Client Specification 9 10 This directory contains work-in-progress English and TLA+ specifications for the Light Client 11 protocol. Implementations of the light client can be found in 12 [Rust](https://github.com/informalsystems/tendermint-rs/tree/master/light-client) and 13 [Go](https://github.com/aakash4dev/cometbft/tree/main/light). 14 15 Light clients are assumed to be initialized once from a trusted source 16 with a trusted header and validator set. The light client 17 protocol allows a client to then securely update its trusted state by requesting and 18 verifying a minimal set of data from a network of full nodes (at least one of which is correct). 19 20 The light client is decomposed into two main components: 21 22 - [Commit Verification](#commit-verification) - verify signed headers and associated validator 23 set changes from a single full node, called primary 24 - [Attack Detection](#attack-detection) - verify commits across multiple full nodes (called secondaries) and detect conflicts (ie. the existence of a lightclient attack) 25 26 In case a lightclient attack is detected, the lightclient submits evidence to a full node which is responsible for "accountability", that is, punishing attackers: 27 28 - [Accountability](#accountability) - given evidence for an attack, compute a set of validators that are responsible for it. 29 30 ## Commit Verification 31 32 The [English specification](verification/verification_001_published.md) describes the light client 33 commit verification problem in terms of the temporal properties 34 [LCV-DIST-SAFE.1](https://github.com/aakash4dev/cometbft/blob/main/spec/light-client/verification/verification_001_published.md#lcv-dist-safe1) and 35 [LCV-DIST-LIVE.1](https://github.com/aakash4dev/cometbft/blob/main/spec/light-client/verification/verification_001_published.md#lcv-dist-live1). 36 Commit verification is assumed to operate within the Cosmos Failure Model, where +2/3 of validators are correct for some time period and 37 validator sets can change arbitrarily at each height. 38 39 A light client protocol is also provided, including all checks that 40 need to be performed on headers, commits, and validator sets 41 to satisfy the temporal properties - so a light client can continuously 42 synchronize with a blockchain. Clients can skip possibly 43 many intermediate headers by exploiting overlap in trusted and untrusted validator sets. 44 When there is not enough overlap, a bisection routine can be used to find a 45 minimal set of headers that do provide the required overlap. 46 47 The [TLA+ specification ver. 001](verification/Lightclient_A_1.tla) 48 is a formal description of the 49 commit verification protocol executed by a client, including the safety and 50 termination, which can be model checked with Apalache. 51 52 A more detailed TLA+ specification of 53 [Light client verification ver. 003](verification/Lightclient_003_draft.tla) 54 is currently under peer review. 55 56 The `MC*.tla` files contain concrete parameters for the 57 [TLA+ specification](verification/Lightclient_A_1.tla), in order to do model checking. 58 For instance, [MC4_3_faulty.tla](verification/MC4_3_faulty.tla) contains the following parameters 59 for the nodes, heights, the trusting period, the clock drifts, 60 correctness of the primary node, and the ratio of the faulty processes: 61 62 ```tla 63 AllNodes == {"n1", "n2", "n3", "n4"} 64 TRUSTED_HEIGHT == 1 65 TARGET_HEIGHT == 3 66 TRUSTING_PERIOD == 1400 \* the trusting period in some time units 67 CLOCK_DRIFT = 10 \* how much we assume the local clock is drifting 68 REAL_CLOCK_DRIFT = 3 \* how much the local clock is actually drifting 69 IS_PRIMARY_CORRECT == FALSE 70 FAULTY_RATIO == <<1, 3>> \* < 1 / 3 faulty validators 71 ``` 72 73 To run a complete set of experiments, clone [apalache](https://github.com/informalsystems/apalache) and [apalache-tests](https://github.com/informalsystems/apalache-tests) into a directory `$DIR` and run the following commands: 74 75 ```sh 76 $DIR/apalache-tests/scripts/mk-run.py --memlimit 28 002bmc-apalache-ok.csv $DIR/apalache . out 77 ./out/run-all.sh 78 ``` 79 80 After the experiments have finished, you can collect the logs by executing the following command: 81 82 ```sh 83 cd ./out 84 $DIR/apalache-tests/scripts/parse-logs.py --human . 85 ``` 86 87 All lines in `results.csv` should report `Deadlock`, which means that the algorithm 88 has terminated and no invariant violation was found. 89 90 Similar to [002bmc-apalache-ok.csv](verification/002bmc-apalache-ok.csv), 91 file [003bmc-apalache-error.csv](verification/003bmc-apalache-error.csv) specifies 92 the set of experiments that should result in counterexamples: 93 94 ```sh 95 $DIR/apalache-tests/scripts/mk-run.py --memlimit 28 003bmc-apalache-error.csv $DIR/apalache . out 96 ./out/run-all.sh 97 ``` 98 99 All lines in `results.csv` should report `Error`. 100 101 The following table summarizes the experimental results for Light client verification 102 version 001. The TLA+ properties can be found in the 103 [TLA+ specification](verification/Lightclient_A_1.tla). 104 The experiments were run in an AWS instance equipped with 32GB 105 RAM and a 4-core Intel® Xeon® CPU E5-2686 v4 @ 2.30GHz CPU. 106 We write “✗=k” when a bug is reported at depth k, and “✓<=k” when 107 no bug is reported up to depth k. 108 109  110 111 The experimental results for version 003 are to be added. 112 113 ## Attack Detection 114 115 The [English specification](detection/detection_003_reviewed.md) 116 defines light client attacks (and how they differ from blockchain 117 forks), and describes the problem of a light client detecting 118 these attacks by communicating with a network of full nodes, 119 where at least one is correct. 120 121 The specification also contains a detection protocol that checks 122 whether the header obtained from the primary via the verification 123 protocol matches corresponding headers provided by the secondaries. 124 If this is not the case, the protocol analyses the verification traces 125 of the involved full nodes 126 and generates 127 [evidence](detection/detection_003_reviewed.md#cmbc-lc-evidence-data1) 128 of misbehavior that can be submitted to a full node so that 129 the faulty validators can be punished. 130 131 The [TLA+ specification](detection/LCDetector_003_draft.tla) 132 is a formal description of the 133 detection protocol for two peers, including the safety and 134 termination, which can be model checked with Apalache. 135 136 The `LCD_MC*.tla` files contain concrete parameters for the 137 [TLA+ specification](detection/LCDetector_003_draft.tla), 138 in order to run the model checker. 139 For instance, [LCD_MC4_4_faulty.tla](./verification/MC4_4_faulty.tla) 140 contains the following parameters 141 for the nodes, heights, the trusting period, the clock drifts, 142 correctness of the nodes, and the ratio of the faulty processes: 143 144 ```tla 145 AllNodes == {"n1", "n2", "n3", "n4"} 146 TRUSTED_HEIGHT == 1 147 TARGET_HEIGHT == 3 148 TRUSTING_PERIOD == 1400 \* the trusting period in some time units 149 CLOCK_DRIFT = 10 \* how much we assume the local clock is drifting 150 REAL_CLOCK_DRIFT = 3 \* how much the local clock is actually drifting 151 IS_PRIMARY_CORRECT == FALSE 152 IS_SECONDARY_CORRECT == FALSE 153 FAULTY_RATIO == <<1, 3>> \* < 1 / 3 faulty validators 154 ``` 155 156 To run a complete set of experiments, clone [apalache](https://github.com/informalsystems/apalache) and [apalache-tests](https://github.com/informalsystems/apalache-tests) into a directory `$DIR` and run the following commands: 157 158 ```sh 159 $DIR/apalache-tests/scripts/mk-run.py --memlimit 28 004bmc-apalache-ok.csv $DIR/apalache . out 160 ./out/run-all.sh 161 ``` 162 163 After the experiments have finished, you can collect the logs by executing the following command: 164 165 ```sh 166 cd ./out 167 $DIR/apalache-tests/scripts/parse-logs.py --human . 168 ``` 169 170 All lines in `results.csv` should report `Deadlock`, which means that the algorithm 171 has terminated and no invariant violation was found. 172 173 Similar to [004bmc-apalache-ok.csv](verification/004bmc-apalache-ok.csv), 174 file [005bmc-apalache-error.csv](verification/005bmc-apalache-error.csv) specifies 175 the set of experiments that should result in counterexamples: 176 177 ```sh 178 $DIR/apalache-tests/scripts/mk-run.py --memlimit 28 005bmc-apalache-error.csv $DIR/apalache . out 179 ./out/run-all.sh 180 ``` 181 182 All lines in `results.csv` should report `Error`. 183 184 The detailed experimental results are to be added soon. 185 186 ## Accountability 187 188 The [English specification](attacks/isolate-attackers_002_reviewed.md) 189 defines the protocol that is executed on a full node upon receiving attack [evidence](detection/detection_003_reviewed.md#cmbc-lc-evidence-data1) from a lightclient. In particular, the protocol handles three types of attacks 190 191 - lunatic 192 - equivocation 193 - amnesia 194 195 We discussed in the [last part](attacks/isolate-attackers_002_reviewed.md#Part-III---Completeness) of the English specification 196 that the non-lunatic cases are defined by having the same validator set in the conflicting blocks. For these cases, 197 computer-aided analysis of [Tendermint Consensus in TLA+](./accountability/README.md) shows that equivocation and amnesia capture all non-lunatic attacks. 198 199 The [TLA+ specification](attacks/Isolation_001_draft.tla) 200 is a formal description of the 201 protocol, including the safety property, which can be model checked with Apalache. 202 203 Similar to the other specifications, [MC_5_3.tla](attacks/MC_5_3.tla) contains concrete parameters to run the model checker. The specification can be checked within seconds. 204 205 [tendermint-accountability](./accountability/README.md)