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