From b270ab8d15410ab4e70e3835ef2bbd3bbf9c48d7 Mon Sep 17 00:00:00 2001 From: Marko Date: Mon, 1 Mar 2021 08:54:08 +0000 Subject: [PATCH] spec: merge rust-spec (#252) --- rust-spec/lightclient/README.md | 202 -------------- .../lightclient/verification/verification.md | 4 - spec/light-client/README.md | 257 +++++++++++++----- .../accountability}/001indinv-apalache.csv | 0 .../light-client/accountability}/MC_n4_f1.tla | 0 .../light-client/accountability}/MC_n4_f2.tla | 0 .../accountability}/MC_n4_f2_amnesia.tla | 0 .../light-client/accountability}/MC_n4_f3.tla | 0 .../light-client/accountability}/MC_n5_f1.tla | 0 .../light-client/accountability}/MC_n5_f2.tla | 0 .../light-client/accountability}/MC_n6_f1.tla | 0 .../README.md} | 10 +- .../light-client/accountability/Synopsis.md | 37 ++- .../TendermintAccDebug_004_draft.tla | 0 .../TendermintAccInv_004_draft.tla | 0 .../TendermintAccTrace_004_draft.tla | 0 .../TendermintAcc_004_draft.tla | 0 .../results/001indinv-apalache-mem-log.svg | 0 .../results/001indinv-apalache-mem.svg | 0 .../results/001indinv-apalache-ncells.svg | 0 .../results/001indinv-apalache-nclauses.svg | 0 .../results/001indinv-apalache-report.md | 1 - .../results/001indinv-apalache-time-log.svg | 0 .../results/001indinv-apalache-time.svg | 0 .../results/001indinv-apalache-unstable.csv | 0 .../light-client/accountability}/run.sh | 0 .../attacks/Blockchain_003_draft.tla | 0 .../attacks/Isolation_001_draft.tla | 0 .../attacks/LCVerificationApi_003_draft.tla | 0 .../light-client}/attacks/MC_5_3.tla | 0 .../attacks/isolate-attackers_001_draft.md | 78 +++--- .../attacks/isolate-attackers_002_reviewed.md | 74 ++--- .../attacks/notes-on-evidence-handling.md | 0 spec/light-client/detection.md | 3 - .../detection/004bmc-apalache-ok.csv | 0 .../detection/005bmc-apalache-error.csv | 0 .../detection/Blockchain_003_draft.tla | 0 .../detection/LCD_MC3_3_faulty.tla | 0 .../detection/LCD_MC3_4_faulty.tla | 0 .../detection/LCD_MC4_4_faulty.tla | 0 .../detection/LCD_MC5_5_faulty.tla | 0 .../detection/LCDetector_003_draft.tla | 0 .../detection/LCVerificationApi_003_draft.tla | 0 .../light-client}/detection/README.md | 6 + .../detection/detection_001_reviewed.md | 0 .../detection/detection_003_reviewed.md | 37 ++- .../light-client}/detection/discussions.md | 0 .../detection/draft-functions.md | 0 .../detection/req-ibc-detection.md | 0 .../light-client}/experiments.png | Bin .../supervisor/supervisor_001_draft.md | 36 +-- .../supervisor/supervisor_001_draft.tla | 0 .../verification/001bmc-apalache.csv | 0 .../verification/002bmc-apalache-ok.csv | 0 .../verification/003bmc-apalache-error.csv | 0 .../verification/004bmc-apalache-ok.csv | 0 .../verification/005bmc-apalache-error.csv | 0 .../verification/Blockchain_002_draft.tla | 0 .../verification/Blockchain_003_draft.tla | 0 .../verification/Blockchain_A_1.tla | 0 .../LCVerificationApi_003_draft.tla | 0 .../verification/Lightclient_002_draft.tla | 0 .../verification/Lightclient_003_draft.tla | 0 .../verification/Lightclient_A_1.tla | 0 .../verification/MC4_3_correct.tla | 0 .../verification/MC4_3_faulty.tla | 0 .../verification/MC4_4_correct.tla | 0 .../verification/MC4_4_correct_drifted.tla | 0 .../verification/MC4_4_faulty.tla | 0 .../verification/MC4_4_faulty_drifted.tla | 0 .../verification/MC4_5_correct.tla | 0 .../verification/MC4_5_faulty.tla | 0 .../verification/MC4_6_faulty.tla | 0 .../verification/MC4_7_faulty.tla | 0 .../verification/MC5_5_correct.tla | 0 .../MC5_5_correct_peer_two_thirds_faulty.tla | 0 .../verification/MC5_5_faulty.tla | 0 .../MC5_5_faulty_peer_two_thirds_faulty.tla | 0 .../verification/MC5_7_faulty.tla | 0 .../verification/MC7_5_faulty.tla | 0 .../verification/MC7_7_faulty.tla | 0 .../README.md} | 6 + .../verification_001_published.md | 5 +- .../verification/verification_002_draft.md | 30 +- 84 files changed, 359 insertions(+), 427 deletions(-) delete mode 100644 rust-spec/lightclient/README.md delete mode 100644 rust-spec/lightclient/verification/verification.md rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/001indinv-apalache.csv (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/MC_n4_f1.tla (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/MC_n4_f2.tla (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/MC_n4_f2_amnesia.tla (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/MC_n4_f3.tla (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/MC_n5_f1.tla (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/MC_n5_f2.tla (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/MC_n6_f1.tla (100%) rename spec/light-client/{accountability.md => accountability/README.md} (99%) rename rust-spec/tendermint-accountability/README.md => spec/light-client/accountability/Synopsis.md (73%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/TendermintAccDebug_004_draft.tla (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/TendermintAccInv_004_draft.tla (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/TendermintAccTrace_004_draft.tla (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/TendermintAcc_004_draft.tla (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/results/001indinv-apalache-mem-log.svg (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/results/001indinv-apalache-mem.svg (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/results/001indinv-apalache-ncells.svg (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/results/001indinv-apalache-nclauses.svg (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/results/001indinv-apalache-report.md (99%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/results/001indinv-apalache-time-log.svg (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/results/001indinv-apalache-time.svg (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/results/001indinv-apalache-unstable.csv (100%) rename {rust-spec/tendermint-accountability => spec/light-client/accountability}/run.sh (100%) rename {rust-spec/lightclient => spec/light-client}/attacks/Blockchain_003_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/attacks/Isolation_001_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/attacks/LCVerificationApi_003_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/attacks/MC_5_3.tla (100%) rename {rust-spec/lightclient => spec/light-client}/attacks/isolate-attackers_001_draft.md (93%) rename {rust-spec/lightclient => spec/light-client}/attacks/isolate-attackers_002_reviewed.md (94%) rename {rust-spec/lightclient => spec/light-client}/attacks/notes-on-evidence-handling.md (100%) delete mode 100644 spec/light-client/detection.md rename {rust-spec/lightclient => spec/light-client}/detection/004bmc-apalache-ok.csv (100%) rename {rust-spec/lightclient => spec/light-client}/detection/005bmc-apalache-error.csv (100%) rename {rust-spec/lightclient => spec/light-client}/detection/Blockchain_003_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/detection/LCD_MC3_3_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/detection/LCD_MC3_4_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/detection/LCD_MC4_4_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/detection/LCD_MC5_5_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/detection/LCDetector_003_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/detection/LCVerificationApi_003_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/detection/README.md (97%) rename {rust-spec/lightclient => spec/light-client}/detection/detection_001_reviewed.md (100%) rename {rust-spec/lightclient => spec/light-client}/detection/detection_003_reviewed.md (97%) rename {rust-spec/lightclient => spec/light-client}/detection/discussions.md (100%) rename {rust-spec/lightclient => spec/light-client}/detection/draft-functions.md (100%) rename {rust-spec/lightclient => spec/light-client}/detection/req-ibc-detection.md (100%) rename {rust-spec/lightclient => spec/light-client}/experiments.png (100%) rename {rust-spec/lightclient => spec/light-client}/supervisor/supervisor_001_draft.md (98%) rename {rust-spec/lightclient => spec/light-client}/supervisor/supervisor_001_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/001bmc-apalache.csv (100%) rename {rust-spec/lightclient => spec/light-client}/verification/002bmc-apalache-ok.csv (100%) rename {rust-spec/lightclient => spec/light-client}/verification/003bmc-apalache-error.csv (100%) rename {rust-spec/lightclient => spec/light-client}/verification/004bmc-apalache-ok.csv (100%) rename {rust-spec/lightclient => spec/light-client}/verification/005bmc-apalache-error.csv (100%) rename {rust-spec/lightclient => spec/light-client}/verification/Blockchain_002_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/Blockchain_003_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/Blockchain_A_1.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/LCVerificationApi_003_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/Lightclient_002_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/Lightclient_003_draft.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/Lightclient_A_1.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC4_3_correct.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC4_3_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC4_4_correct.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC4_4_correct_drifted.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC4_4_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC4_4_faulty_drifted.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC4_5_correct.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC4_5_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC4_6_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC4_7_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC5_5_correct.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC5_5_correct_peer_two_thirds_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC5_5_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC5_5_faulty_peer_two_thirds_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC5_7_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC7_5_faulty.tla (100%) rename {rust-spec/lightclient => spec/light-client}/verification/MC7_7_faulty.tla (100%) rename spec/light-client/{verification.md => verification/README.md} (99%) rename {rust-spec/lightclient => spec/light-client}/verification/verification_001_published.md (99%) rename {rust-spec/lightclient => spec/light-client}/verification/verification_002_draft.md (99%) diff --git a/rust-spec/lightclient/README.md b/rust-spec/lightclient/README.md deleted file mode 100644 index cdecb8fa4c6..00000000000 --- a/rust-spec/lightclient/README.md +++ /dev/null @@ -1,202 +0,0 @@ -# Light Client Specification - -This directory contains work-in-progress English and TLA+ specifications for the Light Client -protocol. Implementations of the light client can be found in -[Rust](https://github.com/informalsystems/tendermint-rs/tree/master/light-client) and -[Go](https://github.com/tendermint/tendermint/tree/master/light). - -Light clients are assumed to be initialized once from a trusted source -with a trusted header and validator set. The light client -protocol allows a client to then securely update its trusted state by requesting and -verifying a minimal set of data from a network of full nodes (at least one of which is correct). - -The light client is decomposed into two main components: - -- [Commit Verification](#Commit-Verification) - verify signed headers and associated validator - set changes from a single full node, called primary -- [Attack Detection](#Attack-Detection) - verify commits across multiple full nodes (called secondaries) and detect conflicts (ie. the existence of a lightclient attack) - -In case a lightclient attack is detected, the lightclient submits evidence to a full node which is responsible for "accountability", that is, punishing attackers: - -- [Accountability](#Accountability) - given evidence for an attack, compute a set of validators that are responsible for it. - -## Commit Verification - -The [English specification](verification/verification_001_published.md) describes the light client -commit verification problem in terms of the temporal properties -[LCV-DIST-SAFE.1](https://github.com/informalsystems/tendermint-rs/blob/master/docs/spec/lightclient/verification/verification_001_published.md#lcv-dist-safe1) and -[LCV-DIST-LIVE.1](https://github.com/informalsystems/tendermint-rs/blob/master/docs/spec/lightclient/verification/verification_001_published.md#lcv-dist-live1). -Commit verification is assumed to operate within the Tendermint Failure Model, where +2/3 of validators are correct for some time period and -validator sets can change arbitrarily at each height. - -A light client protocol is also provided, including all checks that -need to be performed on headers, commits, and validator sets -to satisfy the temporal properties - so a light client can continuously -synchronize with a blockchain. Clients can skip possibly -many intermediate headers by exploiting overlap in trusted and untrusted validator sets. -When there is not enough overlap, a bisection routine can be used to find a -minimal set of headers that do provide the required overlap. - -The [TLA+ specification ver. 001](verification/Lightclient_A_1.tla) -is a formal description of the -commit verification protocol executed by a client, including the safety and -termination, which can be model checked with Apalache. - -A more detailed TLA+ specification of -[Light client verification ver. 003](verification/Lightclient_003_draft.tla) -is currently under peer review. - -The `MC*.tla` files contain concrete parameters for the -[TLA+ specification](verification/Lightclient_A_1.tla), in order to do model checking. -For instance, [MC4_3_faulty.tla](verification/MC4_3_faulty.tla) contains the following parameters -for the nodes, heights, the trusting period, the clock drifts, -correctness of the primary node, and the ratio of the faulty processes: - -```tla -AllNodes == {"n1", "n2", "n3", "n4"} -TRUSTED_HEIGHT == 1 -TARGET_HEIGHT == 3 -TRUSTING_PERIOD == 1400 \* the trusting period in some time units -CLOCK_DRIFT = 10 \* how much we assume the local clock is drifting -REAL_CLOCK_DRIFT = 3 \* how much the local clock is actually drifting -IS_PRIMARY_CORRECT == FALSE -FAULTY_RATIO == <<1, 3>> \* < 1 / 3 faulty validators -``` - -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: - -```sh -$DIR/apalache-tests/scripts/mk-run.py --memlimit 28 002bmc-apalache-ok.csv $DIR/apalache . out -./out/run-all.sh -``` - -After the experiments have finished, you can collect the logs by executing the following command: - -```sh -cd ./out -$DIR/apalache-tests/scripts/parse-logs.py --human . -``` - -All lines in `results.csv` should report `Deadlock`, which means that the algorithm -has terminated and no invariant violation was found. - -Similar to [002bmc-apalache-ok.csv](verification/002bmc-apalache-ok.csv), -file [003bmc-apalache-error.csv](verification/003bmc-apalache-error.csv) specifies -the set of experiments that should result in counterexamples: - -```sh -$DIR/apalache-tests/scripts/mk-run.py --memlimit 28 003bmc-apalache-error.csv $DIR/apalache . out -./out/run-all.sh -``` - -All lines in `results.csv` should report `Error`. - - -The following table summarizes the experimental results for Light client verification -version 001. The TLA+ properties can be found in the -[TLA+ specification](verification/Lightclient_A_1.tla). - The experiments were run in an AWS instance equipped with 32GB -RAM and a 4-core Intel® Xeon® CPU E5-2686 v4 @ 2.30GHz CPU. -We write “✗=k” when a bug is reported at depth k, and “✓<=k” when -no bug is reported up to depth k. - -![Experimental results](experiments.png) - -The experimental results for version 003 are to be added. - -## Attack Detection - -The [English specification](detection/detection_003_reviewed.md) -defines light client attacks (and how they differ from blockchain - forks), and describes the problem of a light client detecting - these attacks by communicating with a network of full nodes, - where at least one is correct. - -The specification also contains a detection protocol that checks -whether the header obtained from the primary via the verification -protocol matches corresponding headers provided by the secondaries. -If this is not the case, the protocol analyses the verification traces -of the involved full nodes -and generates -[evidence](detection/detection_003_reviewed.md#tmbc-lc-evidence-data1) -of misbehavior that can be submitted to a full node so that -the faulty validators can be punished. - -The [TLA+ specification](detection/LCDetector_003_draft.tla) -is a formal description of the -detection protocol for two peers, including the safety and -termination, which can be model checked with Apalache. - - -The `LCD_MC*.tla` files contain concrete parameters for the -[TLA+ specification](detection/LCDetector_003_draft.tla), -in order to run the model checker. -For instance, [LCD_MC4_4_faulty.tla](detection/MC4_4_faulty.tla) -contains the following parameters -for the nodes, heights, the trusting period, the clock drifts, -correctness of the nodes, and the ratio of the faulty processes: - -```tla -AllNodes == {"n1", "n2", "n3", "n4"} -TRUSTED_HEIGHT == 1 -TARGET_HEIGHT == 3 -TRUSTING_PERIOD == 1400 \* the trusting period in some time units -CLOCK_DRIFT = 10 \* how much we assume the local clock is drifting -REAL_CLOCK_DRIFT = 3 \* how much the local clock is actually drifting -IS_PRIMARY_CORRECT == FALSE -IS_SECONDARY_CORRECT == FALSE -FAULTY_RATIO == <<1, 3>> \* < 1 / 3 faulty validators -``` - -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: - -```sh -$DIR/apalache-tests/scripts/mk-run.py --memlimit 28 004bmc-apalache-ok.csv $DIR/apalache . out -./out/run-all.sh -``` - -After the experiments have finished, you can collect the logs by executing the following command: - -```sh -cd ./out -$DIR/apalache-tests/scripts/parse-logs.py --human . -``` - -All lines in `results.csv` should report `Deadlock`, which means that the algorithm -has terminated and no invariant violation was found. - -Similar to [004bmc-apalache-ok.csv](verification/004bmc-apalache-ok.csv), -file [005bmc-apalache-error.csv](verification/005bmc-apalache-error.csv) specifies -the set of experiments that should result in counterexamples: - -```sh -$DIR/apalache-tests/scripts/mk-run.py --memlimit 28 005bmc-apalache-error.csv $DIR/apalache . out -./out/run-all.sh -``` - -All lines in `results.csv` should report `Error`. - -The detailed experimental results are to be added soon. - -## Accountability - - -The [English specification](attacks/isolate-attackers_002_reviewed.md) -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 -- lunatic -- equivocation -- amnesia - -We discussed in the [last part](attacks/isolate-attackers_002_reviewed.md#Part-III---Completeness) of the English specification -that the non-lunatic cases are defined by having the same validator set in the conflicting blocks. For these cases, -computer-aided analysis of [Tendermint Consensus in TLA+][tendermint-accountability] shows that equivocation and amnesia capture all non-lunatic attacks. - - -The [TLA+ specification](attacks/Isolation_001_draft.tla) -is a formal description of the -protocol, including the safety property, which can be model checked with Apalache. - -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. - -[tendermint-accountability]: -https://github.com/tendermint/spec/blob/master/rust-spec/tendermint-accountability/README.md diff --git a/rust-spec/lightclient/verification/verification.md b/rust-spec/lightclient/verification/verification.md deleted file mode 100644 index 09226ab640c..00000000000 --- a/rust-spec/lightclient/verification/verification.md +++ /dev/null @@ -1,4 +0,0 @@ -We changed the naming convention and versioning of specifications. -See [verification_001_published.md](./verification_001_published.md) -for the file that used to be called `verification.md`. There are also newer -versions of this specification in this directory. \ No newline at end of file diff --git a/spec/light-client/README.md b/spec/light-client/README.md index 573eddbafc8..42f20d46c19 100644 --- a/spec/light-client/README.md +++ b/spec/light-client/README.md @@ -5,66 +5,201 @@ parent: order: 5 --- -NOTE: This specification is under heavy development and is not yet complete nor -accurate. +# Light Client Specification + +This directory contains work-in-progress English and TLA+ specifications for the Light Client +protocol. Implementations of the light client can be found in +[Rust](https://github.com/informalsystems/tendermint-rs/tree/master/light-client) and +[Go](https://github.com/tendermint/tendermint/tree/master/light). -## Contents +Light clients are assumed to be initialized once from a trusted source +with a trusted header and validator set. The light client +protocol allows a client to then securely update its trusted state by requesting and +verifying a minimal set of data from a network of full nodes (at least one of which is correct). + +The light client is decomposed into two main components: + +- [Commit Verification](#Commit-Verification) - verify signed headers and associated validator + set changes from a single full node, called primary +- [Attack Detection](#Attack-Detection) - verify commits across multiple full nodes (called secondaries) and detect conflicts (ie. the existence of a lightclient attack) + +In case a lightclient attack is detected, the lightclient submits evidence to a full node which is responsible for "accountability", that is, punishing attackers: + +- [Accountability](#Accountability) - given evidence for an attack, compute a set of validators that are responsible for it. + +## Commit Verification + +The [English specification](verification/verification_001_published.md) describes the light client +commit verification problem in terms of the temporal properties +[LCV-DIST-SAFE.1](https://github.com/informalsystems/tendermint-rs/blob/master/docs/spec/lightclient/verification/verification_001_published.md#lcv-dist-safe1) and +[LCV-DIST-LIVE.1](https://github.com/informalsystems/tendermint-rs/blob/master/docs/spec/lightclient/verification/verification_001_published.md#lcv-dist-live1). +Commit verification is assumed to operate within the Tendermint Failure Model, where +2/3 of validators are correct for some time period and +validator sets can change arbitrarily at each height. + +A light client protocol is also provided, including all checks that +need to be performed on headers, commits, and validator sets +to satisfy the temporal properties - so a light client can continuously +synchronize with a blockchain. Clients can skip possibly +many intermediate headers by exploiting overlap in trusted and untrusted validator sets. +When there is not enough overlap, a bisection routine can be used to find a +minimal set of headers that do provide the required overlap. + +The [TLA+ specification ver. 001](verification/Lightclient_A_1.tla) +is a formal description of the +commit verification protocol executed by a client, including the safety and +termination, which can be model checked with Apalache. + +A more detailed TLA+ specification of +[Light client verification ver. 003](verification/Lightclient_003_draft.tla) +is currently under peer review. + +The `MC*.tla` files contain concrete parameters for the +[TLA+ specification](verification/Lightclient_A_1.tla), in order to do model checking. +For instance, [MC4_3_faulty.tla](verification/MC4_3_faulty.tla) contains the following parameters +for the nodes, heights, the trusting period, the clock drifts, +correctness of the primary node, and the ratio of the faulty processes: + +```tla +AllNodes == {"n1", "n2", "n3", "n4"} +TRUSTED_HEIGHT == 1 +TARGET_HEIGHT == 3 +TRUSTING_PERIOD == 1400 \* the trusting period in some time units +CLOCK_DRIFT = 10 \* how much we assume the local clock is drifting +REAL_CLOCK_DRIFT = 3 \* how much the local clock is actually drifting +IS_PRIMARY_CORRECT == FALSE +FAULTY_RATIO == <<1, 3>> \* < 1 / 3 faulty validators +``` + +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: + +```sh +$DIR/apalache-tests/scripts/mk-run.py --memlimit 28 002bmc-apalache-ok.csv $DIR/apalache . out +./out/run-all.sh +``` + +After the experiments have finished, you can collect the logs by executing the following command: + +```sh +cd ./out +$DIR/apalache-tests/scripts/parse-logs.py --human . +``` + +All lines in `results.csv` should report `Deadlock`, which means that the algorithm +has terminated and no invariant violation was found. + +Similar to [002bmc-apalache-ok.csv](verification/002bmc-apalache-ok.csv), +file [003bmc-apalache-error.csv](verification/003bmc-apalache-error.csv) specifies +the set of experiments that should result in counterexamples: + +```sh +$DIR/apalache-tests/scripts/mk-run.py --memlimit 28 003bmc-apalache-error.csv $DIR/apalache . out +./out/run-all.sh +``` + +All lines in `results.csv` should report `Error`. + +The following table summarizes the experimental results for Light client verification +version 001. The TLA+ properties can be found in the +[TLA+ specification](verification/Lightclient_A_1.tla). + The experiments were run in an AWS instance equipped with 32GB +RAM and a 4-core Intel® Xeon® CPU E5-2686 v4 @ 2.30GHz CPU. +We write “✗=k” when a bug is reported at depth k, and “✓<=k” when +no bug is reported up to depth k. + +![Experimental results](experiments.png) + +The experimental results for version 003 are to be added. + +## Attack Detection + +The [English specification](detection/detection_003_reviewed.md) +defines light client attacks (and how they differ from blockchain +forks), and describes the problem of a light client detecting +these attacks by communicating with a network of full nodes, +where at least one is correct. + +The specification also contains a detection protocol that checks +whether the header obtained from the primary via the verification +protocol matches corresponding headers provided by the secondaries. +If this is not the case, the protocol analyses the verification traces +of the involved full nodes +and generates +[evidence](detection/detection_003_reviewed.md#tmbc-lc-evidence-data1) +of misbehavior that can be submitted to a full node so that +the faulty validators can be punished. + +The [TLA+ specification](detection/LCDetector_003_draft.tla) +is a formal description of the +detection protocol for two peers, including the safety and +termination, which can be model checked with Apalache. + +The `LCD_MC*.tla` files contain concrete parameters for the +[TLA+ specification](detection/LCDetector_003_draft.tla), +in order to run the model checker. +For instance, [LCD_MC4_4_faulty.tla](detection/MC4_4_faulty.tla) +contains the following parameters +for the nodes, heights, the trusting period, the clock drifts, +correctness of the nodes, and the ratio of the faulty processes: + +```tla +AllNodes == {"n1", "n2", "n3", "n4"} +TRUSTED_HEIGHT == 1 +TARGET_HEIGHT == 3 +TRUSTING_PERIOD == 1400 \* the trusting period in some time units +CLOCK_DRIFT = 10 \* how much we assume the local clock is drifting +REAL_CLOCK_DRIFT = 3 \* how much the local clock is actually drifting +IS_PRIMARY_CORRECT == FALSE +IS_SECONDARY_CORRECT == FALSE +FAULTY_RATIO == <<1, 3>> \* < 1 / 3 faulty validators +``` + +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: + +```sh +$DIR/apalache-tests/scripts/mk-run.py --memlimit 28 004bmc-apalache-ok.csv $DIR/apalache . out +./out/run-all.sh +``` + +After the experiments have finished, you can collect the logs by executing the following command: + +```sh +cd ./out +$DIR/apalache-tests/scripts/parse-logs.py --human . +``` + +All lines in `results.csv` should report `Deadlock`, which means that the algorithm +has terminated and no invariant violation was found. -- [Motivation](#motivation) -- [Structure](#structure) -- [Core Verification](./verification.md) -- [Fork Detection](./detection.md) -- [Fork Accountability](./accountability.md) - -## Motivation - -The Tendermint Light Client is motivated by the need for a light weight protocol -to sync with a Tendermint blockchain, with the least processing necessary to -securely verify a recent state. The protocol consists of managing trusted validator -sets and trusted block headers, and is based primarily on checking hashes -and verifying Tendermint commit signatures. - -Motivating use cases include: - -- Light Node: a daemon that syncs a blockchain to the latest committed header by making RPC requests to full nodes. -- State Sync: a reactor that syncs a blockchain to a recent committed state by making P2P requests to full nodes. -- IBC Client: an ABCI application library that syncs a blockchain to a recent committed header by receiving proof-carrying -transactions from "IBC relayers", who make RPC requests to full nodes on behalf of the IBC clients. - -## Structure - -### Components - -The Tendermint Light Client consists of three primary components: - -- [Core Verification](./verification.md): verifying hashes, signatures, and validator set changes -- [Fork Detection](./detection.md): talking to multiple peers to detect Byzantine behaviour -- [Fork Accountability](./accountability.md): analyzing Byzantine behaviour to hold validators accountable. - -While every light client must perform core verification and fork detection -to achieve their prescribed security level, fork accountability is expected to -be done by full nodes and validators, and is thus more accurately a component of -the full node consensus protocol, though it is included here since it is -primarily concerned with providing security to light clients. - -A schematic of the core verification and fork detection components in -a Light Node are depicted below. The schematic is quite similar for other use cases. -Note that fork accountability is not depicted, as it is the responsibility of the -full nodes. - -![Light Client Diagram](./assets/light-node-image.png). - -### Synchrony - -Light clients are fundamentally synchronous protocols, -where security is restricted by the interval during which a validator can be punished -for Byzantine behaviour. We assume here that such intervals have fixed and known minimal duration -referred to commonly as a blockchain's Unbonding Period. - -A secure light client must guarantee that all three components - -core verification, fork detection, and fork accountability - -each with their own synchrony assumptions and fault model, can execute -sequentially and to completion within the given Unbonding Period. - -TODO: define all the synchrony parameters used in the protocol and their -relation to the Unbonding Period. +Similar to [004bmc-apalache-ok.csv](verification/004bmc-apalache-ok.csv), +file [005bmc-apalache-error.csv](verification/005bmc-apalache-error.csv) specifies +the set of experiments that should result in counterexamples: + +```sh +$DIR/apalache-tests/scripts/mk-run.py --memlimit 28 005bmc-apalache-error.csv $DIR/apalache . out +./out/run-all.sh +``` + +All lines in `results.csv` should report `Error`. + +The detailed experimental results are to be added soon. + +## Accountability + +The [English specification](attacks/isolate-attackers_002_reviewed.md) +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 + +- lunatic +- equivocation +- amnesia + +We discussed in the [last part](attacks/isolate-attackers_002_reviewed.md#Part-III---Completeness) of the English specification +that the non-lunatic cases are defined by having the same validator set in the conflicting blocks. For these cases, +computer-aided analysis of [Tendermint Consensus in TLA+](./accountability/README.md) shows that equivocation and amnesia capture all non-lunatic attacks. + +The [TLA+ specification](attacks/Isolation_001_draft.tla) +is a formal description of the +protocol, including the safety property, which can be model checked with Apalache. + +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. + +[tendermint-accountability](./accountability/README.md) diff --git a/rust-spec/tendermint-accountability/001indinv-apalache.csv b/spec/light-client/accountability/001indinv-apalache.csv similarity index 100% rename from rust-spec/tendermint-accountability/001indinv-apalache.csv rename to spec/light-client/accountability/001indinv-apalache.csv diff --git a/rust-spec/tendermint-accountability/MC_n4_f1.tla b/spec/light-client/accountability/MC_n4_f1.tla similarity index 100% rename from rust-spec/tendermint-accountability/MC_n4_f1.tla rename to spec/light-client/accountability/MC_n4_f1.tla diff --git a/rust-spec/tendermint-accountability/MC_n4_f2.tla b/spec/light-client/accountability/MC_n4_f2.tla similarity index 100% rename from rust-spec/tendermint-accountability/MC_n4_f2.tla rename to spec/light-client/accountability/MC_n4_f2.tla diff --git a/rust-spec/tendermint-accountability/MC_n4_f2_amnesia.tla b/spec/light-client/accountability/MC_n4_f2_amnesia.tla similarity index 100% rename from rust-spec/tendermint-accountability/MC_n4_f2_amnesia.tla rename to spec/light-client/accountability/MC_n4_f2_amnesia.tla diff --git a/rust-spec/tendermint-accountability/MC_n4_f3.tla b/spec/light-client/accountability/MC_n4_f3.tla similarity index 100% rename from rust-spec/tendermint-accountability/MC_n4_f3.tla rename to spec/light-client/accountability/MC_n4_f3.tla diff --git a/rust-spec/tendermint-accountability/MC_n5_f1.tla b/spec/light-client/accountability/MC_n5_f1.tla similarity index 100% rename from rust-spec/tendermint-accountability/MC_n5_f1.tla rename to spec/light-client/accountability/MC_n5_f1.tla diff --git a/rust-spec/tendermint-accountability/MC_n5_f2.tla b/spec/light-client/accountability/MC_n5_f2.tla similarity index 100% rename from rust-spec/tendermint-accountability/MC_n5_f2.tla rename to spec/light-client/accountability/MC_n5_f2.tla diff --git a/rust-spec/tendermint-accountability/MC_n6_f1.tla b/spec/light-client/accountability/MC_n6_f1.tla similarity index 100% rename from rust-spec/tendermint-accountability/MC_n6_f1.tla rename to spec/light-client/accountability/MC_n6_f1.tla diff --git a/spec/light-client/accountability.md b/spec/light-client/accountability/README.md similarity index 99% rename from spec/light-client/accountability.md rename to spec/light-client/accountability/README.md index c46495553fe..bb872649bb9 100644 --- a/spec/light-client/accountability.md +++ b/spec/light-client/accountability/README.md @@ -1,3 +1,10 @@ +--- +order: 1 +parent: + title: Accountability + order: 4 +--- + # Fork accountability ## Problem Statement @@ -8,8 +15,7 @@ Tendermint consensus guarantees the following specifications for all heights: * validity -- the decided block satisfies the predefined predicate *valid()*. * termination -- all correct full nodes eventually decide, -if the -faulty validators have less than 1/3 of voting power in the current validator set. In the case where this assumption +If the faulty validators have less than 1/3 of voting power in the current validator set. In the case where this assumption does not hold, each of the specification may be violated. The agreement property says that for a given height, any two correct validators that decide on a block for that height decide on the same block. That the block was indeed generated by the blockchain, can be verified starting from a trusted (genesis) block, and checking that all subsequent blocks are properly signed. diff --git a/rust-spec/tendermint-accountability/README.md b/spec/light-client/accountability/Synopsis.md similarity index 73% rename from rust-spec/tendermint-accountability/README.md rename to spec/light-client/accountability/Synopsis.md index ac321d45742..76da3868c72 100644 --- a/rust-spec/tendermint-accountability/README.md +++ b/spec/light-client/accountability/Synopsis.md @@ -1,53 +1,54 @@ + # Synopsis - + A TLA+ specification of a simplified Tendermint consensus, tuned for fork accountability. The simplifications are as follows: - - the procotol runs for one height, that is, one-shot consensus +- the procotol runs for one height, that is, one-shot consensus - - this specification focuses on safety, so timeouts are modelled with +- this specification focuses on safety, so timeouts are modelled with with non-determinism - - the proposer function is non-determinstic, no fairness is assumed +- the proposer function is non-determinstic, no fairness is assumed - - the messages by the faulty processes are injected right in the initial states +- the messages by the faulty processes are injected right in the initial states - - every process has the voting power of 1 +- every process has the voting power of 1 - - hashes are modelled as identity +- hashes are modelled as identity Having the above assumptions in mind, the specification follows the pseudo-code - of the Tendermint paper: https://arxiv.org/abs/1807.04938 + of the Tendermint paper: Byzantine processes can demonstrate arbitrary behavior, including no communication. However, we have to show that under the collective evidence collected by the correct processes, at least `f+1` Byzantine processes demonstrate one of the following behaviors: - - Equivocation: a Byzantine process sends two different values +- Equivocation: a Byzantine process sends two different values in the same round. - - Amnesia: a Byzantine process locks a value, although it has locked +- Amnesia: a Byzantine process locks a value, although it has locked another value in the past. # TLA+ modules - - - [TendermintAcc_004_draft](TendermintAcc_004_draft.tla) is the protocol + +- [TendermintAcc_004_draft](TendermintAcc_004_draft.tla) is the protocol specification, - - [TendermintAccInv_004_draft](TendermintAccInv_004_draft.tla) contains an +- [TendermintAccInv_004_draft](TendermintAccInv_004_draft.tla) contains an inductive invariant for establishing the protocol safety as well as the forking cases, - - `MC_n_f`, e.g., [MC_n4_f1](MC_n4_f1.tla), contains fixed constants for +- `MC_n_f`, e.g., [MC_n4_f1](MC_n4_f1.tla), contains fixed constants for model checking with the [Apalache model checker](https://github.com/informalsystems/apalache), - - [TendermintAccTrace_004_draft](TendermintAccTrace_004_draft.tla) shows how +- [TendermintAccTrace_004_draft](TendermintAccTrace_004_draft.tla) shows how to restrict the execution space to a fixed sequence of actions (e.g., to instantiate a counterexample), - - [TendermintAccDebug_004_draft](TendermintAccDebug_004_draft.tla) contains +- [TendermintAccDebug_004_draft](TendermintAccDebug_004_draft.tla) contains the useful definitions for debugging the protocol specification with TLC and Apalache. @@ -90,7 +91,7 @@ THEOREM AgreementOrFork == ~FaultyQuorum /\ TypedInv => Accountability ``` -# Model checking results +# Model checking results Check the report on [model checking with Apalache](./results/001indinv-apalache-report.md). @@ -102,5 +103,3 @@ To run the model checking experiments, use the script: This script assumes that the apalache build is available in `~/devl/apalache-unstable`. - - diff --git a/rust-spec/tendermint-accountability/TendermintAccDebug_004_draft.tla b/spec/light-client/accountability/TendermintAccDebug_004_draft.tla similarity index 100% rename from rust-spec/tendermint-accountability/TendermintAccDebug_004_draft.tla rename to spec/light-client/accountability/TendermintAccDebug_004_draft.tla diff --git a/rust-spec/tendermint-accountability/TendermintAccInv_004_draft.tla b/spec/light-client/accountability/TendermintAccInv_004_draft.tla similarity index 100% rename from rust-spec/tendermint-accountability/TendermintAccInv_004_draft.tla rename to spec/light-client/accountability/TendermintAccInv_004_draft.tla diff --git a/rust-spec/tendermint-accountability/TendermintAccTrace_004_draft.tla b/spec/light-client/accountability/TendermintAccTrace_004_draft.tla similarity index 100% rename from rust-spec/tendermint-accountability/TendermintAccTrace_004_draft.tla rename to spec/light-client/accountability/TendermintAccTrace_004_draft.tla diff --git a/rust-spec/tendermint-accountability/TendermintAcc_004_draft.tla b/spec/light-client/accountability/TendermintAcc_004_draft.tla similarity index 100% rename from rust-spec/tendermint-accountability/TendermintAcc_004_draft.tla rename to spec/light-client/accountability/TendermintAcc_004_draft.tla diff --git a/rust-spec/tendermint-accountability/results/001indinv-apalache-mem-log.svg b/spec/light-client/accountability/results/001indinv-apalache-mem-log.svg similarity index 100% rename from rust-spec/tendermint-accountability/results/001indinv-apalache-mem-log.svg rename to spec/light-client/accountability/results/001indinv-apalache-mem-log.svg diff --git a/rust-spec/tendermint-accountability/results/001indinv-apalache-mem.svg b/spec/light-client/accountability/results/001indinv-apalache-mem.svg similarity index 100% rename from rust-spec/tendermint-accountability/results/001indinv-apalache-mem.svg rename to spec/light-client/accountability/results/001indinv-apalache-mem.svg diff --git a/rust-spec/tendermint-accountability/results/001indinv-apalache-ncells.svg b/spec/light-client/accountability/results/001indinv-apalache-ncells.svg similarity index 100% rename from rust-spec/tendermint-accountability/results/001indinv-apalache-ncells.svg rename to spec/light-client/accountability/results/001indinv-apalache-ncells.svg diff --git a/rust-spec/tendermint-accountability/results/001indinv-apalache-nclauses.svg b/spec/light-client/accountability/results/001indinv-apalache-nclauses.svg similarity index 100% rename from rust-spec/tendermint-accountability/results/001indinv-apalache-nclauses.svg rename to spec/light-client/accountability/results/001indinv-apalache-nclauses.svg diff --git a/rust-spec/tendermint-accountability/results/001indinv-apalache-report.md b/spec/light-client/accountability/results/001indinv-apalache-report.md similarity index 99% rename from rust-spec/tendermint-accountability/results/001indinv-apalache-report.md rename to spec/light-client/accountability/results/001indinv-apalache-report.md index d63a935985c..0c14742c536 100644 --- a/rust-spec/tendermint-accountability/results/001indinv-apalache-report.md +++ b/spec/light-client/accountability/results/001indinv-apalache-report.md @@ -1,6 +1,5 @@ # Results of 001indinv-apalache - ## 1. Awesome plots ### 1.1. Time (logarithmic scale) diff --git a/rust-spec/tendermint-accountability/results/001indinv-apalache-time-log.svg b/spec/light-client/accountability/results/001indinv-apalache-time-log.svg similarity index 100% rename from rust-spec/tendermint-accountability/results/001indinv-apalache-time-log.svg rename to spec/light-client/accountability/results/001indinv-apalache-time-log.svg diff --git a/rust-spec/tendermint-accountability/results/001indinv-apalache-time.svg b/spec/light-client/accountability/results/001indinv-apalache-time.svg similarity index 100% rename from rust-spec/tendermint-accountability/results/001indinv-apalache-time.svg rename to spec/light-client/accountability/results/001indinv-apalache-time.svg diff --git a/rust-spec/tendermint-accountability/results/001indinv-apalache-unstable.csv b/spec/light-client/accountability/results/001indinv-apalache-unstable.csv similarity index 100% rename from rust-spec/tendermint-accountability/results/001indinv-apalache-unstable.csv rename to spec/light-client/accountability/results/001indinv-apalache-unstable.csv diff --git a/rust-spec/tendermint-accountability/run.sh b/spec/light-client/accountability/run.sh similarity index 100% rename from rust-spec/tendermint-accountability/run.sh rename to spec/light-client/accountability/run.sh diff --git a/rust-spec/lightclient/attacks/Blockchain_003_draft.tla b/spec/light-client/attacks/Blockchain_003_draft.tla similarity index 100% rename from rust-spec/lightclient/attacks/Blockchain_003_draft.tla rename to spec/light-client/attacks/Blockchain_003_draft.tla diff --git a/rust-spec/lightclient/attacks/Isolation_001_draft.tla b/spec/light-client/attacks/Isolation_001_draft.tla similarity index 100% rename from rust-spec/lightclient/attacks/Isolation_001_draft.tla rename to spec/light-client/attacks/Isolation_001_draft.tla diff --git a/rust-spec/lightclient/attacks/LCVerificationApi_003_draft.tla b/spec/light-client/attacks/LCVerificationApi_003_draft.tla similarity index 100% rename from rust-spec/lightclient/attacks/LCVerificationApi_003_draft.tla rename to spec/light-client/attacks/LCVerificationApi_003_draft.tla diff --git a/rust-spec/lightclient/attacks/MC_5_3.tla b/spec/light-client/attacks/MC_5_3.tla similarity index 100% rename from rust-spec/lightclient/attacks/MC_5_3.tla rename to spec/light-client/attacks/MC_5_3.tla diff --git a/rust-spec/lightclient/attacks/isolate-attackers_001_draft.md b/spec/light-client/attacks/isolate-attackers_001_draft.md similarity index 93% rename from rust-spec/lightclient/attacks/isolate-attackers_001_draft.md rename to spec/light-client/attacks/isolate-attackers_001_draft.md index 54f02cccd9b..e4f585f4a8f 100644 --- a/rust-spec/lightclient/attacks/isolate-attackers_001_draft.md +++ b/spec/light-client/attacks/isolate-attackers_001_draft.md @@ -1,25 +1,25 @@ -*** This is the beginning of an unfinished draft. Don't continue reading! *** # Lightclient Attackers Isolation -Adversarial nodes may have the incentive to lie to a lightclient about the state of a Tendermint blockchain. An attempt to do so is called attack. Light client [verification][verification] checks incoming data by checking a so-called "commit", which is a forwarded set of signed messages that is (supposedly) produced during executing Tendermint consensus. Thus, an attack boils down to creating and signing Tendermint consensus messages in deviation from the Tendermint consensus algorithm rules. +> Warning: This is the beginning of an unfinished draft. Don't continue reading! -As Tendermint consensus and light client verification is safe under the assumption of more than 2/3 of correct voting power per block [[TMBC-FM-2THIRDS]][TMBC-FM-2THIRDS-link], this implies that if there was an attack then [[TMBC-FM-2THIRDS]][TMBC-FM-2THIRDS-link] was violated, that is, there is a block such that -- validators deviated from the protocol, and -- these validators represent more than 1/3 of the voting power in that block. +Adversarial nodes may have the incentive to lie to a lightclient about the state of a Tendermint blockchain. An attempt to do so is called attack. Light client [verification][verification] checks incoming data by checking a so-called "commit", which is a forwarded set of signed messages that is (supposedly) produced during executing Tendermint consensus. Thus, an attack boils down to creating and signing Tendermint consensus messages in deviation from the Tendermint consensus algorithm rules. -In the case of an [attack][node-based-attack-characterization], the lightclient [attack detection mechanism][detection] computes data, so called evidence [[LC-DATA-EVIDENCE.1]][LC-DATA-EVIDENCE-link], that can be used -- to proof that there has been attack [[TMBC-LC-EVIDENCE-DATA.1]][TMBC-LC-EVIDENCE-DATA-link] and -- as basis to find the actual nodes that deviated from the Tendermint protocol. +As Tendermint consensus and light client verification is safe under the assumption of more than 2/3 of correct voting power per block [[TMBC-FM-2THIRDS]][TMBC-FM-2THIRDS-link], this implies that if there was an attack then [[TMBC-FM-2THIRDS]][TMBC-FM-2THIRDS-link] was violated, that is, there is a block such that +- validators deviated from the protocol, and +- these validators represent more than 1/3 of the voting power in that block. +In the case of an [attack][node-based-attack-characterization], the lightclient [attack detection mechanism][detection] computes data, so called evidence [[LC-DATA-EVIDENCE.1]][LC-DATA-EVIDENCE-link], that can be used +- to proof that there has been attack [[TMBC-LC-EVIDENCE-DATA.1]][TMBC-LC-EVIDENCE-DATA-link] and +- as basis to find the actual nodes that deviated from the Tendermint protocol. This specification considers how a full node in a Tendermint blockchain can isolate a set of attackers that launched the attack. The set should satisfy + - the set does not contain a correct validator - the set contains validators that represent more than 1/3 of the voting power of a block that is still within the unbonding period - # Outline **TODO** when preparing a version for broader review. @@ -30,7 +30,8 @@ For definitions of data structures used here, in particular LightBlocks [[LCV-DA # Part II - Definition of the Problem -The specification of the [detection mechanism][detection] describes +The specification of the [detection mechanism][detection] describes + - what is a light client attack, - conditions under which the detector will detect a light client attack, - and the format of the output data, called evidence, in the case an attack is detected. The format is defined in @@ -48,11 +49,12 @@ and a prefix of the blockchain `bc` at least up to height `ev.ConflictingBlock.H We assume that the full node is synchronized with the blockchain and has reached the height `ev.ConflictingBlock.Header.Height + 1`. - #### **[FN-INV-Output.1]** -When an output is generated it satisfies the following properties: + +When an output is generated it satisfies the following properties: + - If - - `bc[CommonHeight].bfttime` is within the unbonding period w.r.t. the time at the full node, + - `bc[CommonHeight].bfttime` is within the unbonding period w.r.t. the time at the full node, - `ev.ConflictingBlock.Header != bc[ev.ConflictingBlock.Header.Height]` - Validators in `ev.ConflictingBlock.Commit` represent more than 1/3 of the voting power in `bc[ev.CommonHeight].NextValidators` - Then: A set of validators in `bc[CommonHeight].NextValidators` that @@ -60,7 +62,6 @@ When an output is generated it satisfies the following properties: - signed Tendermint consensus messages for height `ev.ConflictingBlock.Header.Height` by violating the Tendermint consensus protocol. - Else: the empty set. - # Part IV - Protocol Here we discuss how to solve the problem of isolating misbehaving processes. We describe the function `isolateMisbehavingProcesses` as well as all the helping functions below. In [Part V](#part-v---Completeness), we discuss why the solution is complete based on result from analysis with automated tools. @@ -72,9 +73,10 @@ Here we discuss how to solve the problem of isolating misbehaving processes. We > Describe solution (in English), decomposition into functions, where communication to other components happens. #### **[LCAI-FUNC-MAIN.1]** + ```go func isolateMisbehavingProcesses(ev LightClientAttackEvidence, bc Blockchain) []ValidatorAddress { - + reference := bc[ev.conflictingBlock.Header.Height].Header ev_header := ev.conflictingBlock.Header @@ -87,18 +89,19 @@ func isolateMisbehavingProcesses(ev LightClientAttackEvidence, bc Blockchain) [] bonded_vals := Addresses(bc[ev.CommonHeight].NextValidators) return intersection(signatories,bonded_vals) - } + } // If this point is reached the validator sets in reference and ev_header are identical else if RoundOf(ref_commit) == RoundOf(ev_commit) { // equivocation light client attack return intersection(Signers(ref_commit), Signers(ev_commit)) - } + } else { - // amnesia light client attack + // amnesia light client attack return IsolateAmnesiaAttacker(ev, bc) - } + } } ``` + - Implementation comment - If the full node has only reached height `ev.conflictingBlock.Header.Height` then `bc[ev.conflictingBlock.Header.Height + 1].Header.LastCommit` refers to the locally stored commit for this height. (This commit must be present by the precondition on `length(bc)`.) - We check in the precondition that the unbonding period is not expired. However, since time moves on, before handing the validators over Cosmos SDK, the time needs to be checked again to satisfy the contract which requires that only bonded validators are reported. This passing of validators to the SDK is out of scope of this specification. @@ -109,27 +112,30 @@ func isolateMisbehavingProcesses(ev LightClientAttackEvidence, bc Blockchain) [] - TODO: input light blocks pass basic validation - Expected postcondition - [[FN-INV-Output.1]](#FN-INV-Output1) holds -- Error condition +- Error condition - returns an error if precondition is violated. - ### Details of the Functions #### **[LCAI-FUNC-VVU.1]** + ```go func ValidAndVerifiedUnbonding(trusted LightBlock, untrusted LightBlock) Result ``` + - Conditions are identical to [[LCV-FUNC-VALID.2]][LCV-FUNC-VALID.link] except the precondition "*trusted.Header.Time > now - trustingPeriod*" is substituted with - `trusted.Header.Time > now - UnbondingPeriod` #### **[LCAI-FUNC-NONVALID.1]** + ```go func violatesTMValidity(ref Header, ev Header) boolean ``` + - Implementation remarks - checks whether the evidence header `ev` violates the validity property of Tendermint Consensus, by checking agains a reference header - Expected precondition - - `ref.Height == ev.Height` + - `ref.Height == ev.Height` - Expected postcondition - returns evaluation of the following disjunction **[[LCAI-NONVALID-OUTPUT.1]]** == @@ -139,53 +145,52 @@ func violatesTMValidity(ref Header, ev Header) boolean `ref.AppHash != ev.AppHash` or `ref.LastResultsHash != ev.LastResultsHash` - ```go -func IsolateAmnesiaAttacker(ev LightClientAttackEvidence, bc Blockchain) []ValidatorAddress +func IsolateAmnesiaAttacker(ev LightClientAttackEvidence, bc Blockchain) []ValidatorAddress ``` + - Implementation remarks **TODO:** What should we do here? Refer to the accountability doc? - Expected postcondition **TODO:** What should we do here? Refer to the accountability doc? ```go -func RoundOf(commit Commit) []ValidatorAddress +func RoundOf(commit Commit) []ValidatorAddress ``` + - Expected precondition - `commit` is well-formed. In particular all votes are from the same round `r`. - Expected postcondition - returns round `r` that is encoded in all the votes of the commit ```go -func Signers(commit Commit) []ValidatorAddress +func Signers(commit Commit) []ValidatorAddress ``` + - Expected postcondition - returns all validator addresses in `commit` ```go func Addresses(vals Validator[]) ValidatorAddress[] ``` + - Expected postcondition - returns all validator addresses in `vals` - - # Part V - Completeness As discussed in the beginning of this document, an attack boils down to creating and signing Tendermint consensus messages in deviation from the Tendermint consensus algorithm rules. The main function `isolateMisbehavingProcesses` distinguishes three kinds of wrongly signing messages, namely, + - lunatic: signing invalid blocks -- equivocation: double-signing valid blocks in the same consensus round +- equivocation: double-signing valid blocks in the same consensus round - amnesia: signing conflicting blocks in different consensus rounds, without having seen a quorum of messages that would have allowed to do so. -The question is whether this captures all attacks. +The question is whether this captures all attacks. First observe that the first checking in `isolateMisbehavingProcesses` is `violatesTMValidity`. It takes care of lunatic attacks. If this check passes, that is, if `violatesTMValidity` returns `FALSE` this means that [FN-NONVALID-OUTPUT] evaluates to false, which implies that `ref.ValidatorsHash = ev.ValidatorsHash`. Hence after `violatesTMValidity`, all the involved validators are the ones from the blockchain. It is thus sufficient to analyze one instance of Tendermint consensus with a fixed group membership (set of validators). Also it is sufficient to consider two different valid consensus values, that is, binary consensus. **TODO** we have analyzed Tendermint consensus with TLA+ and have accompanied Galois in an independent study of the protocol based on [Ivy proofs](https://github.com/tendermint/spec/tree/master/ivy-proofs). - - - # References [[supervisor]] The specification of the light client supervisor. @@ -194,16 +199,15 @@ First observe that the first checking in `isolateMisbehavingProcesses` is `viola [[detection]] The specification of the light client attack detection mechanism. -[supervisor]: +[supervisor]: https://github.com/tendermint/spec/blob/master/rust-spec/lightclient/supervisor/supervisor_001_draft.md [verification]: https://github.com/tendermint/spec/blob/master/rust-spec/lightclient/verification/verification_002_draft.md -[detection]: +[detection]: https://github.com/tendermint/spec/blob/master/rust-spec/lightclient/detection/detection_003_reviewed.md - -[LC-DATA-EVIDENCE-link]: +[LC-DATA-EVIDENCE-link]: https://github.com/tendermint/spec/blob/master/rust-spec/lightclient/detection/detection_003_reviewed.md#lc-data-evidence1 [TMBC-LC-EVIDENCE-DATA-link]: diff --git a/rust-spec/lightclient/attacks/isolate-attackers_002_reviewed.md b/spec/light-client/attacks/isolate-attackers_002_reviewed.md similarity index 94% rename from rust-spec/lightclient/attacks/isolate-attackers_002_reviewed.md rename to spec/light-client/attacks/isolate-attackers_002_reviewed.md index c4e270efa66..febcc10a827 100644 --- a/rust-spec/lightclient/attacks/isolate-attackers_002_reviewed.md +++ b/spec/light-client/attacks/isolate-attackers_002_reviewed.md @@ -2,22 +2,21 @@ Adversarial nodes may have the incentive to lie to a lightclient about the state of a Tendermint blockchain. An attempt to do so is called attack. Light client [verification][verification] checks incoming data by checking a so-called "commit", which is a forwarded set of signed messages that is (supposedly) produced during executing Tendermint consensus. Thus, an attack boils down to creating and signing Tendermint consensus messages in deviation from the Tendermint consensus algorithm rules. -As Tendermint consensus and light client verification is safe under the assumption of more than 2/3 of correct voting power per block [[TMBC-FM-2THIRDS]][TMBC-FM-2THIRDS-link], this implies that if there was an attack then [[TMBC-FM-2THIRDS]][TMBC-FM-2THIRDS-link] was violated, that is, there is a block such that -- validators deviated from the protocol, and -- these validators represent more than 1/3 of the voting power in that block. - -In the case of an [attack][node-based-attack-characterization], the lightclient [attack detection mechanism][detection] computes data, so called evidence [[LC-DATA-EVIDENCE.1]][LC-DATA-EVIDENCE-link], that can be used -- to proof that there has been attack [[TMBC-LC-EVIDENCE-DATA.1]][TMBC-LC-EVIDENCE-DATA-link] and -- as basis to find the actual nodes that deviated from the Tendermint protocol. +As Tendermint consensus and light client verification is safe under the assumption of more than 2/3 of correct voting power per block [[TMBC-FM-2THIRDS]][TMBC-FM-2THIRDS-link], this implies that if there was an attack then [[TMBC-FM-2THIRDS]][TMBC-FM-2THIRDS-link] was violated, that is, there is a block such that +- validators deviated from the protocol, and +- these validators represent more than 1/3 of the voting power in that block. +In the case of an [attack][node-based-attack-characterization], the lightclient [attack detection mechanism][detection] computes data, so called evidence [[LC-DATA-EVIDENCE.1]][LC-DATA-EVIDENCE-link], that can be used +- to proof that there has been attack [[TMBC-LC-EVIDENCE-DATA.1]][TMBC-LC-EVIDENCE-DATA-link] and +- as basis to find the actual nodes that deviated from the Tendermint protocol. This specification considers how a full node in a Tendermint blockchain can isolate a set of attackers that launched the attack. The set should satisfy + - the set does not contain a correct validator - the set contains validators that represent more than 1/3 of the voting power of a block that is still within the unbonding period - # Outline After providing the [problem statement](#Part-I---Basics-and-Definition-of-the-Problem), we specify the [isolator function](#Part-II---Protocol) and close with the discussion about its [correctness](#Part-III---Completeness) which is based on computer-aided analysis of Tendermint Consensus. @@ -26,8 +25,8 @@ After providing the [problem statement](#Part-I---Basics-and-Definition-of-the-P For definitions of data structures used here, in particular LightBlocks [[LCV-DATA-LIGHTBLOCK.1]](https://github.com/tendermint/spec/blob/master/rust-spec/lightclient/verification/verification_002_draft.md#lcv-data-lightblock1), we refer to the specification of [Light Client Verification][verification]. +The specification of the [detection mechanism][detection] describes -The specification of the [detection mechanism][detection] describes - what is a light client attack, - conditions under which the detector will detect a light client attack, - and the format of the output data, called evidence, in the case an attack is detected. The format is defined in @@ -45,11 +44,12 @@ and a prefix of the blockchain `bc` at least up to height `ev.ConflictingBlock.H We assume that the full node is synchronized with the blockchain and has reached the height `ev.ConflictingBlock.Header.Height + 1`. - #### **[LCAI-INV-Output.1]** -When an output is generated it satisfies the following properties: + +When an output is generated it satisfies the following properties: + - If - - `bc[CommonHeight].bfttime` is within the unbonding period w.r.t. the time at the full node, + - `bc[CommonHeight].bfttime` is within the unbonding period w.r.t. the time at the full node, - `ev.ConflictingBlock.Header != bc[ev.ConflictingBlock.Header.Height]` - Validators in `ev.ConflictingBlock.Commit` represent more than 1/3 of the voting power in `bc[ev.CommonHeight].NextValidators` - Then: The output is a set of validators in `bc[CommonHeight].NextValidators` that @@ -57,7 +57,6 @@ When an output is generated it satisfies the following properties: - signed Tendermint consensus messages for height `ev.ConflictingBlock.Header.Height` by violating the Tendermint consensus protocol. - Else: the empty set. - # Part II - Protocol Here we discuss how to solve the problem of isolating misbehaving processes. We describe the function `isolateMisbehavingProcesses` as well as all the helping functions below. In [Part III](#part-III---Completeness), we discuss why the solution is complete based on result from analysis with automated tools. @@ -69,9 +68,10 @@ Here we discuss how to solve the problem of isolating misbehaving processes. We We first check whether the conflicting block can indeed be verified from the common height. We then first check whether it was a lunatic attack (violating validity). If this is not the case, we check for equivocation. If this also is not the case, we start the on-chain [accountability protocol](https://docs.google.com/document/d/11ZhMsCj3y7zIZz4udO9l25xqb0kl7gmWqNpGVRzOeyY/edit). #### **[LCAI-FUNC-MAIN.1]** + ```go func isolateMisbehavingProcesses(ev LightClientAttackEvidence, bc Blockchain) []ValidatorAddress { - + reference := bc[ev.conflictingBlock.Header.Height].Header ev_header := ev.conflictingBlock.Header @@ -84,18 +84,19 @@ func isolateMisbehavingProcesses(ev LightClientAttackEvidence, bc Blockchain) [] bonded_vals := Addresses(bc[ev.CommonHeight].NextValidators) return intersection(signatories,bonded_vals) - } + } // If this point is reached the validator sets in reference and ev_header are identical else if RoundOf(ref_commit) == RoundOf(ev_commit) { // equivocation light client attack return intersection(Signers(ref_commit), Signers(ev_commit)) - } + } else { - // amnesia light client attack + // amnesia light client attack return IsolateAmnesiaAttacker(ev, bc) - } + } } ``` + - Implementation comment - If the full node has only reached height `ev.conflictingBlock.Header.Height` then `bc[ev.conflictingBlock.Header.Height + 1].Header.LastCommit` refers to the locally stored commit for this height. (This commit must be present by the precondition on `length(bc)`.) - We check in the precondition that the unbonding period is not expired. However, since time moves on, before handing the validators over Cosmos SDK, the time needs to be checked again to satisfy the contract which requires that only bonded validators are reported. This passing of validators to the SDK is out of scope of this specification. @@ -106,27 +107,30 @@ func isolateMisbehavingProcesses(ev LightClientAttackEvidence, bc Blockchain) [] - `ev.conflictingBlock` satisfies basic validation (in particular all signed messages in the Commit are from the same round) - Expected postcondition - [[FN-INV-Output.1]](#FN-INV-Output1) holds -- Error condition +- Error condition - returns an error if precondition is violated. - ### Details of the Functions #### **[LCAI-FUNC-VVU.1]** + ```go func ValidAndVerifiedUnbonding(trusted LightBlock, untrusted LightBlock) Result ``` + - Conditions are identical to [[LCV-FUNC-VALID.2]][LCV-FUNC-VALID.link] except the precondition "*trusted.Header.Time > now - trustingPeriod*" is substituted with - `trusted.Header.Time > now - UnbondingPeriod` #### **[LCAI-FUNC-NONVALID.1]** + ```go func violatesTMValidity(ref Header, ev Header) boolean ``` + - Implementation remarks - checks whether the evidence header `ev` violates the validity property of Tendermint Consensus, by checking against a reference header - Expected precondition - - `ref.Height == ev.Height` + - `ref.Height == ev.Height` - Expected postcondition - returns evaluation of the following disjunction **[LCAI-NONVALID-OUTPUT.1]** == @@ -136,18 +140,19 @@ func violatesTMValidity(ref Header, ev Header) boolean `ref.AppHash != ev.AppHash` or `ref.LastResultsHash != ev.LastResultsHash` - ```go -func IsolateAmnesiaAttacker(ev LightClientAttackEvidence, bc Blockchain) []ValidatorAddress +func IsolateAmnesiaAttacker(ev LightClientAttackEvidence, bc Blockchain) []ValidatorAddress ``` + - Implementation remarks - This triggers the [query/response protocol](https://docs.google.com/document/d/11ZhMsCj3y7zIZz4udO9l25xqb0kl7gmWqNpGVRzOeyY/edit). - Expected postcondition - returns attackers according to [LCAI-INV-Output.1]. ```go -func RoundOf(commit Commit) []ValidatorAddress +func RoundOf(commit Commit) []ValidatorAddress ``` + - Expected precondition - `commit` is well-formed. In particular all votes are from the same round `r`. - Expected postcondition @@ -156,35 +161,33 @@ func RoundOf(commit Commit) []ValidatorAddress - reports error if precondition is violated ```go -func Signers(commit Commit) []ValidatorAddress +func Signers(commit Commit) []ValidatorAddress ``` + - Expected postcondition - returns all validator addresses in `commit` ```go func Addresses(vals Validator[]) ValidatorAddress[] ``` + - Expected postcondition - returns all validator addresses in `vals` - - # Part III - Completeness As discussed in the beginning of this document, an attack boils down to creating and signing Tendermint consensus messages in deviation from the Tendermint consensus algorithm rules. The main function `isolateMisbehavingProcesses` distinguishes three kinds of wrongly signed messages, namely, + - lunatic: signing invalid blocks -- equivocation: double-signing valid blocks in the same consensus round +- equivocation: double-signing valid blocks in the same consensus round - amnesia: signing conflicting blocks in different consensus rounds, without having seen a quorum of messages that would have allowed to do so. -The question is whether this captures all attacks. +The question is whether this captures all attacks. First observe that the first check in `isolateMisbehavingProcesses` is `violatesTMValidity`. It takes care of lunatic attacks. If this check passes, that is, if `violatesTMValidity` returns `FALSE` this means that [[LCAI-NONVALID-OUTPUT.1]](#LCAI-FUNC-NONVALID1]) evaluates to false, which implies that `ref.ValidatorsHash = ev.ValidatorsHash`. Hence, after `violatesTMValidity`, all the involved validators are the ones from the blockchain. It is thus sufficient to analyze one instance of Tendermint consensus with a fixed group membership (set of validators). Also, as we have two different blocks for the same height, it is sufficient to consider two different valid consensus values, that is, binary consensus. For this fixed group membership, we have analyzed the attacks using the TLA+ specification of [Tendermint Consensus in TLA+][tendermint-accountability]. We checked that indeed the only possible scenarios that can lead to violation of agreement are **equivocation** and **amnesia**. An independent study by Galois of the protocol based on [Ivy proofs](https://github.com/tendermint/spec/tree/master/ivy-proofs) led to the same conclusion. - - - # References [[supervisor]] The specification of the light client supervisor. @@ -198,16 +201,15 @@ For this fixed group membership, we have analyzed the attacks using the TLA+ spe [tendermint-accountability]: https://github.com/tendermint/spec/blob/master/rust-spec/tendermint-accountability/README.md -[supervisor]: +[supervisor]: https://github.com/tendermint/spec/blob/master/rust-spec/lightclient/supervisor/supervisor_001_draft.md [verification]: https://github.com/tendermint/spec/blob/master/rust-spec/lightclient/verification/verification_002_draft.md -[detection]: +[detection]: https://github.com/tendermint/spec/blob/master/rust-spec/lightclient/detection/detection_003_reviewed.md - -[LC-DATA-EVIDENCE-link]: +[LC-DATA-EVIDENCE-link]: https://github.com/tendermint/spec/blob/master/rust-spec/lightclient/detection/detection_003_reviewed.md#lc-data-evidence1 [TMBC-LC-EVIDENCE-DATA-link]: diff --git a/rust-spec/lightclient/attacks/notes-on-evidence-handling.md b/spec/light-client/attacks/notes-on-evidence-handling.md similarity index 100% rename from rust-spec/lightclient/attacks/notes-on-evidence-handling.md rename to spec/light-client/attacks/notes-on-evidence-handling.md diff --git a/spec/light-client/detection.md b/spec/light-client/detection.md deleted file mode 100644 index d0a0ad1da9e..00000000000 --- a/spec/light-client/detection.md +++ /dev/null @@ -1,3 +0,0 @@ -# Detection - -TODO diff --git a/rust-spec/lightclient/detection/004bmc-apalache-ok.csv b/spec/light-client/detection/004bmc-apalache-ok.csv similarity index 100% rename from rust-spec/lightclient/detection/004bmc-apalache-ok.csv rename to spec/light-client/detection/004bmc-apalache-ok.csv diff --git a/rust-spec/lightclient/detection/005bmc-apalache-error.csv b/spec/light-client/detection/005bmc-apalache-error.csv similarity index 100% rename from rust-spec/lightclient/detection/005bmc-apalache-error.csv rename to spec/light-client/detection/005bmc-apalache-error.csv diff --git a/rust-spec/lightclient/detection/Blockchain_003_draft.tla b/spec/light-client/detection/Blockchain_003_draft.tla similarity index 100% rename from rust-spec/lightclient/detection/Blockchain_003_draft.tla rename to spec/light-client/detection/Blockchain_003_draft.tla diff --git a/rust-spec/lightclient/detection/LCD_MC3_3_faulty.tla b/spec/light-client/detection/LCD_MC3_3_faulty.tla similarity index 100% rename from rust-spec/lightclient/detection/LCD_MC3_3_faulty.tla rename to spec/light-client/detection/LCD_MC3_3_faulty.tla diff --git a/rust-spec/lightclient/detection/LCD_MC3_4_faulty.tla b/spec/light-client/detection/LCD_MC3_4_faulty.tla similarity index 100% rename from rust-spec/lightclient/detection/LCD_MC3_4_faulty.tla rename to spec/light-client/detection/LCD_MC3_4_faulty.tla diff --git a/rust-spec/lightclient/detection/LCD_MC4_4_faulty.tla b/spec/light-client/detection/LCD_MC4_4_faulty.tla similarity index 100% rename from rust-spec/lightclient/detection/LCD_MC4_4_faulty.tla rename to spec/light-client/detection/LCD_MC4_4_faulty.tla diff --git a/rust-spec/lightclient/detection/LCD_MC5_5_faulty.tla b/spec/light-client/detection/LCD_MC5_5_faulty.tla similarity index 100% rename from rust-spec/lightclient/detection/LCD_MC5_5_faulty.tla rename to spec/light-client/detection/LCD_MC5_5_faulty.tla diff --git a/rust-spec/lightclient/detection/LCDetector_003_draft.tla b/spec/light-client/detection/LCDetector_003_draft.tla similarity index 100% rename from rust-spec/lightclient/detection/LCDetector_003_draft.tla rename to spec/light-client/detection/LCDetector_003_draft.tla diff --git a/rust-spec/lightclient/detection/LCVerificationApi_003_draft.tla b/spec/light-client/detection/LCVerificationApi_003_draft.tla similarity index 100% rename from rust-spec/lightclient/detection/LCVerificationApi_003_draft.tla rename to spec/light-client/detection/LCVerificationApi_003_draft.tla diff --git a/rust-spec/lightclient/detection/README.md b/spec/light-client/detection/README.md similarity index 97% rename from rust-spec/lightclient/detection/README.md rename to spec/light-client/detection/README.md index 8f92bdaa281..50d8ab6fe1b 100644 --- a/rust-spec/lightclient/detection/README.md +++ b/spec/light-client/detection/README.md @@ -1,3 +1,9 @@ +--- +order: 1 +parent: + title: Fork Detection + order: 2 +--- # Tendermint fork detection and IBC fork detection diff --git a/rust-spec/lightclient/detection/detection_001_reviewed.md b/spec/light-client/detection/detection_001_reviewed.md similarity index 100% rename from rust-spec/lightclient/detection/detection_001_reviewed.md rename to spec/light-client/detection/detection_001_reviewed.md diff --git a/rust-spec/lightclient/detection/detection_003_reviewed.md b/spec/light-client/detection/detection_003_reviewed.md similarity index 97% rename from rust-spec/lightclient/detection/detection_003_reviewed.md rename to spec/light-client/detection/detection_003_reviewed.md index 89e920f19be..812f80d1c7f 100644 --- a/rust-spec/lightclient/detection/detection_003_reviewed.md +++ b/spec/light-client/detection/detection_003_reviewed.md @@ -58,37 +58,33 @@ a new light block, the light client first does the light block (and the trace of light blocks that led to it) with the secondaries using this specification. - # Outline - [Part I](#part-i---Tendermint-Consensus-and-Light-Client-Attacks): Formal definitions of lightclient attacks, based on basic properties of Tendermint consensus. - - [Node-based characterization of + - [Node-based characterization of attacks](#Node-based-characterization-of-attacks). The definition of attacks used in the problem statement of - this specification. + this specification. - - [Block-based characterization of attacks](#Block-based-characterization-of-attacks). Alternative definitions + - [Block-based characterization of attacks](#Block-based-characterization-of-attacks). Alternative definitions provided for future reference. - - [Part II](#part-ii---problem-statement): Problem statement of lightclient attack detection - - [Informal Problem Statement](#informal-problem-statement) - - [Assumptions](#Assumptions) - - [Definitions](#definitions) - - [Distributed Problem statement](#Distributed-Problem-statement) + - [Informal Problem Statement](#informal-problem-statement) + - [Assumptions](#Assumptions) + - [Definitions](#definitions) + - [Distributed Problem statement](#Distributed-Problem-statement) - [Part III](#part-iii---protocol): The protocol - - [Functions and Data defined in other Specifications](#Functions-and-Data-defined-in-other-Specifications) - - [Outline of Solution](#Outline-of-solution) - - [Details of the functions](#Details-of-the-functions) - - [Correctness arguments](#Correctness-arguments) - - + - [Functions and Data defined in other Specifications](#Functions-and-Data-defined-in-other-Specifications) + - [Outline of Solution](#Outline-of-solution) + - [Details of the functions](#Details-of-the-functions) + - [Correctness arguments](#Correctness-arguments) # Part I - Tendermint Consensus and Light Client Attacks @@ -264,7 +260,6 @@ of v(i) and v(i+1) such that > - check that v(i+1) differs from its block at that height, and > - verify v(i+1) in one step from v(i) as v is a verification trace. - #### **[TMBC-LC-EVIDENCE-DATA.1]** To prove the attack to p1, because of Point E1, it is sufficient to @@ -420,7 +415,6 @@ one. We can thus base liveness arguments of the detector on the assumptions that correct full nodes reliably talk to the detector. - #### **[LCD-A-CorrFull.1]** At all times there is at least one correct full @@ -576,6 +570,7 @@ then the secondary is replaced before the detector terminates. ### From the [supervisor][supervisor] [[LC-FUNC-REPLACE-SECONDARY.1]][repl] + ```go Replace_Secondary(addr Address, root-of-trust LightBlock) ``` @@ -583,6 +578,7 @@ Replace_Secondary(addr Address, root-of-trust LightBlock) ### From the [verifier][verification] [[LCV-FUNC-MAIN.2]][vtt] + ```go func VerifyToTarget(primary PeerID, root LightBlock, targetHeight Height) (LightStore, Result) @@ -628,7 +624,7 @@ func AttackDetector(root LightBlock, primary_trace []LightBlock) Replace_Secondary(root); } else if lb.Header != primary_trace.Latest().Header { - + // we replay the primary trace with the secondary, in // order to generate evidence that we can submit to the // secondary. We return the evidence + the trace the @@ -732,9 +728,9 @@ func CreateEvidenceForPeer(peer PeerID, root LightBlock, trace LightStore) ## Correctness arguments -#### On the existence of evidence +#### On the existence of evidence -**Proposition.** In the case of attack, +**Proposition.** In the case of attack, evidence [[TMBC-LC-ATTACK-EVIDENCE.1]](#TMBC-LC-ATTACK-EVIDENCE1) exists. *Proof.* First observe that @@ -750,7 +746,6 @@ Now by contradiction assume there is no evidence. Thus i = h - 1 we get **NOT E1(h-1)**. Contradiction. QED. - #### Argument for [[LCD-DIST-INV-ATTACK.1]](#LCD-DIST-INV-ATTACK1) Under the assumption that root and trace are a verification trace, diff --git a/rust-spec/lightclient/detection/discussions.md b/spec/light-client/detection/discussions.md similarity index 100% rename from rust-spec/lightclient/detection/discussions.md rename to spec/light-client/detection/discussions.md diff --git a/rust-spec/lightclient/detection/draft-functions.md b/spec/light-client/detection/draft-functions.md similarity index 100% rename from rust-spec/lightclient/detection/draft-functions.md rename to spec/light-client/detection/draft-functions.md diff --git a/rust-spec/lightclient/detection/req-ibc-detection.md b/spec/light-client/detection/req-ibc-detection.md similarity index 100% rename from rust-spec/lightclient/detection/req-ibc-detection.md rename to spec/light-client/detection/req-ibc-detection.md diff --git a/rust-spec/lightclient/experiments.png b/spec/light-client/experiments.png similarity index 100% rename from rust-spec/lightclient/experiments.png rename to spec/light-client/experiments.png diff --git a/rust-spec/lightclient/supervisor/supervisor_001_draft.md b/spec/light-client/supervisor/supervisor_001_draft.md similarity index 98% rename from rust-spec/lightclient/supervisor/supervisor_001_draft.md rename to spec/light-client/supervisor/supervisor_001_draft.md index df7a71b3eed..3c3d45d87ba 100644 --- a/rust-spec/lightclient/supervisor/supervisor_001_draft.md +++ b/spec/light-client/supervisor/supervisor_001_draft.md @@ -6,7 +6,6 @@ This specification in done in parallel with updates on the verification specification. So some hyperlinks have to be placed to the correct files eventually. - # Light Client Sequential Supervisor The light client implements a read operation of a @@ -92,7 +91,6 @@ Upon initialization, the light client gets as input a header of the blockchain, or the genesis file of the blockchain, and eventually stores a header of the blockchain. - #### **[LC-SEQ-LIVE.1]** The light client gets a sequence of heights as inputs. For each input @@ -140,13 +138,11 @@ that contains light blocks (that contain a header). **TODO:** reference light store invariant [LCV-INV-LS-ROOT.2] once verification is merged - #### **[LC-DIST-SAFE.1]** It is always the case that every header in *LightStore* was generated by an instance of Tendermint consensus. - #### **[LC-DIST-LIVE.1]** Whenever the light client gets a new height *h* as input, @@ -171,8 +167,6 @@ follows from [[LCD-DIST-INV-STORE.1]](TODO) [[LCD-DIST-LIVE.1]](TODO) - - # Part IV - Light Client Supervisor Protocol We provide a specification for a sequential Light Client Supervisor. @@ -203,7 +197,6 @@ block but were not cross-checked are stored as "verified" > performance is worth it, we keep for future versions/discussion of > lightclient protocols. - ## Definitions ### Peers @@ -268,8 +261,6 @@ Replace_Secondary(addr Address, root-of-trust LightBlock) - Error condition - if precondition is violated - - ### Data Types The core data structure of the protocol is the LightBlock. @@ -301,7 +292,6 @@ type LightStore struct { We use the functions that the LightStore exposes, which are defined in the [verification specification](TODO). - ### Inputs The lightclient is initialized with LCInitData @@ -369,11 +359,10 @@ func makeblock (genesisDoc GenesisDoc) (lightBlock LightBlock)) ### Configuration Parameters - #### **[LC-INV-ROOT-AGREED.1]** In the Sequential-Supervisor, it is always the case that the primary -and all secondaries agree on lightStore.Latest(). +and all secondaries agree on lightStore.Latest(). ### Assumptions @@ -436,7 +425,7 @@ func Sequential-Supervisor (initdata LCInitData) (Error) { if result == OK { output(LightStore.Get(targetHeight)); - // we only output a trusted lightblock + // we only output a trusted lightblock } else { return result @@ -449,13 +438,13 @@ func Sequential-Supervisor (initdata LCInitData) (Error) { - Implementation remark - infinite loop unless a light client attack is detected - - In typical implementations (e.g., the one in Rust), - there are mutliple input actions: + - In typical implementations (e.g., the one in Rust), + there are mutliple input actions: `VerifytoLatest`, `LatestTrusted`, and `GetStatus`. The information can be easily obtained from the lightstore, so that we do not treat these requests explicitly here but just consider - the request for a block of a given height which requires more - involved computation and communication. + the request for a block of a given height which requires more + involved computation and communication. - Expected precondition - *LCInitData* contains a genesis file or a lightblock. - Expected postcondition @@ -519,8 +508,8 @@ func InitLightClient (initData LCInitData) (LightStore, Error) { } // cross-check - auxLS := new LightStore - auxLS.Add(current) + auxLS := new LightStore + auxLS.Add(current) Evidences := AttackDetector(genesisBlock, auxLS) if Evidences.Empty { newBlock := current @@ -567,12 +556,12 @@ func VerifyAndDetect (lightStore LightStore, targetHeight Height) if b1.State == StateTrusted { // block already there and trusted return (lightStore, ResultSuccess) - } - else { + } + else { // We have a lightblock in the store, but it has not been // cross-checked by now. We do that now. root_of_trust, auxLS := lightstore.TraceTo(b1); - + // Cross-check Evidences := AttackDetector(root_of_trust, auxLS); if Evidences.Empty { @@ -584,7 +573,7 @@ func VerifyAndDetect (lightStore LightStore, targetHeight Height) } else { // there is an attack, we exit - submitEvidence(Evidences); + submitEvidence(Evidences); return(lightStore, ErrorAttack); } } @@ -646,4 +635,3 @@ func VerifyAndDetect (lightStore LightStore, targetHeight Height) - [LC-DATA-PEERLIST-INV.1] is violated ---- - diff --git a/rust-spec/lightclient/supervisor/supervisor_001_draft.tla b/spec/light-client/supervisor/supervisor_001_draft.tla similarity index 100% rename from rust-spec/lightclient/supervisor/supervisor_001_draft.tla rename to spec/light-client/supervisor/supervisor_001_draft.tla diff --git a/rust-spec/lightclient/verification/001bmc-apalache.csv b/spec/light-client/verification/001bmc-apalache.csv similarity index 100% rename from rust-spec/lightclient/verification/001bmc-apalache.csv rename to spec/light-client/verification/001bmc-apalache.csv diff --git a/rust-spec/lightclient/verification/002bmc-apalache-ok.csv b/spec/light-client/verification/002bmc-apalache-ok.csv similarity index 100% rename from rust-spec/lightclient/verification/002bmc-apalache-ok.csv rename to spec/light-client/verification/002bmc-apalache-ok.csv diff --git a/rust-spec/lightclient/verification/003bmc-apalache-error.csv b/spec/light-client/verification/003bmc-apalache-error.csv similarity index 100% rename from rust-spec/lightclient/verification/003bmc-apalache-error.csv rename to spec/light-client/verification/003bmc-apalache-error.csv diff --git a/rust-spec/lightclient/verification/004bmc-apalache-ok.csv b/spec/light-client/verification/004bmc-apalache-ok.csv similarity index 100% rename from rust-spec/lightclient/verification/004bmc-apalache-ok.csv rename to spec/light-client/verification/004bmc-apalache-ok.csv diff --git a/rust-spec/lightclient/verification/005bmc-apalache-error.csv b/spec/light-client/verification/005bmc-apalache-error.csv similarity index 100% rename from rust-spec/lightclient/verification/005bmc-apalache-error.csv rename to spec/light-client/verification/005bmc-apalache-error.csv diff --git a/rust-spec/lightclient/verification/Blockchain_002_draft.tla b/spec/light-client/verification/Blockchain_002_draft.tla similarity index 100% rename from rust-spec/lightclient/verification/Blockchain_002_draft.tla rename to spec/light-client/verification/Blockchain_002_draft.tla diff --git a/rust-spec/lightclient/verification/Blockchain_003_draft.tla b/spec/light-client/verification/Blockchain_003_draft.tla similarity index 100% rename from rust-spec/lightclient/verification/Blockchain_003_draft.tla rename to spec/light-client/verification/Blockchain_003_draft.tla diff --git a/rust-spec/lightclient/verification/Blockchain_A_1.tla b/spec/light-client/verification/Blockchain_A_1.tla similarity index 100% rename from rust-spec/lightclient/verification/Blockchain_A_1.tla rename to spec/light-client/verification/Blockchain_A_1.tla diff --git a/rust-spec/lightclient/verification/LCVerificationApi_003_draft.tla b/spec/light-client/verification/LCVerificationApi_003_draft.tla similarity index 100% rename from rust-spec/lightclient/verification/LCVerificationApi_003_draft.tla rename to spec/light-client/verification/LCVerificationApi_003_draft.tla diff --git a/rust-spec/lightclient/verification/Lightclient_002_draft.tla b/spec/light-client/verification/Lightclient_002_draft.tla similarity index 100% rename from rust-spec/lightclient/verification/Lightclient_002_draft.tla rename to spec/light-client/verification/Lightclient_002_draft.tla diff --git a/rust-spec/lightclient/verification/Lightclient_003_draft.tla b/spec/light-client/verification/Lightclient_003_draft.tla similarity index 100% rename from rust-spec/lightclient/verification/Lightclient_003_draft.tla rename to spec/light-client/verification/Lightclient_003_draft.tla diff --git a/rust-spec/lightclient/verification/Lightclient_A_1.tla b/spec/light-client/verification/Lightclient_A_1.tla similarity index 100% rename from rust-spec/lightclient/verification/Lightclient_A_1.tla rename to spec/light-client/verification/Lightclient_A_1.tla diff --git a/rust-spec/lightclient/verification/MC4_3_correct.tla b/spec/light-client/verification/MC4_3_correct.tla similarity index 100% rename from rust-spec/lightclient/verification/MC4_3_correct.tla rename to spec/light-client/verification/MC4_3_correct.tla diff --git a/rust-spec/lightclient/verification/MC4_3_faulty.tla b/spec/light-client/verification/MC4_3_faulty.tla similarity index 100% rename from rust-spec/lightclient/verification/MC4_3_faulty.tla rename to spec/light-client/verification/MC4_3_faulty.tla diff --git a/rust-spec/lightclient/verification/MC4_4_correct.tla b/spec/light-client/verification/MC4_4_correct.tla similarity index 100% rename from rust-spec/lightclient/verification/MC4_4_correct.tla rename to spec/light-client/verification/MC4_4_correct.tla diff --git a/rust-spec/lightclient/verification/MC4_4_correct_drifted.tla b/spec/light-client/verification/MC4_4_correct_drifted.tla similarity index 100% rename from rust-spec/lightclient/verification/MC4_4_correct_drifted.tla rename to spec/light-client/verification/MC4_4_correct_drifted.tla diff --git a/rust-spec/lightclient/verification/MC4_4_faulty.tla b/spec/light-client/verification/MC4_4_faulty.tla similarity index 100% rename from rust-spec/lightclient/verification/MC4_4_faulty.tla rename to spec/light-client/verification/MC4_4_faulty.tla diff --git a/rust-spec/lightclient/verification/MC4_4_faulty_drifted.tla b/spec/light-client/verification/MC4_4_faulty_drifted.tla similarity index 100% rename from rust-spec/lightclient/verification/MC4_4_faulty_drifted.tla rename to spec/light-client/verification/MC4_4_faulty_drifted.tla diff --git a/rust-spec/lightclient/verification/MC4_5_correct.tla b/spec/light-client/verification/MC4_5_correct.tla similarity index 100% rename from rust-spec/lightclient/verification/MC4_5_correct.tla rename to spec/light-client/verification/MC4_5_correct.tla diff --git a/rust-spec/lightclient/verification/MC4_5_faulty.tla b/spec/light-client/verification/MC4_5_faulty.tla similarity index 100% rename from rust-spec/lightclient/verification/MC4_5_faulty.tla rename to spec/light-client/verification/MC4_5_faulty.tla diff --git a/rust-spec/lightclient/verification/MC4_6_faulty.tla b/spec/light-client/verification/MC4_6_faulty.tla similarity index 100% rename from rust-spec/lightclient/verification/MC4_6_faulty.tla rename to spec/light-client/verification/MC4_6_faulty.tla diff --git a/rust-spec/lightclient/verification/MC4_7_faulty.tla b/spec/light-client/verification/MC4_7_faulty.tla similarity index 100% rename from rust-spec/lightclient/verification/MC4_7_faulty.tla rename to spec/light-client/verification/MC4_7_faulty.tla diff --git a/rust-spec/lightclient/verification/MC5_5_correct.tla b/spec/light-client/verification/MC5_5_correct.tla similarity index 100% rename from rust-spec/lightclient/verification/MC5_5_correct.tla rename to spec/light-client/verification/MC5_5_correct.tla diff --git a/rust-spec/lightclient/verification/MC5_5_correct_peer_two_thirds_faulty.tla b/spec/light-client/verification/MC5_5_correct_peer_two_thirds_faulty.tla similarity index 100% rename from rust-spec/lightclient/verification/MC5_5_correct_peer_two_thirds_faulty.tla rename to spec/light-client/verification/MC5_5_correct_peer_two_thirds_faulty.tla diff --git a/rust-spec/lightclient/verification/MC5_5_faulty.tla b/spec/light-client/verification/MC5_5_faulty.tla similarity index 100% rename from rust-spec/lightclient/verification/MC5_5_faulty.tla rename to spec/light-client/verification/MC5_5_faulty.tla diff --git a/rust-spec/lightclient/verification/MC5_5_faulty_peer_two_thirds_faulty.tla b/spec/light-client/verification/MC5_5_faulty_peer_two_thirds_faulty.tla similarity index 100% rename from rust-spec/lightclient/verification/MC5_5_faulty_peer_two_thirds_faulty.tla rename to spec/light-client/verification/MC5_5_faulty_peer_two_thirds_faulty.tla diff --git a/rust-spec/lightclient/verification/MC5_7_faulty.tla b/spec/light-client/verification/MC5_7_faulty.tla similarity index 100% rename from rust-spec/lightclient/verification/MC5_7_faulty.tla rename to spec/light-client/verification/MC5_7_faulty.tla diff --git a/rust-spec/lightclient/verification/MC7_5_faulty.tla b/spec/light-client/verification/MC7_5_faulty.tla similarity index 100% rename from rust-spec/lightclient/verification/MC7_5_faulty.tla rename to spec/light-client/verification/MC7_5_faulty.tla diff --git a/rust-spec/lightclient/verification/MC7_7_faulty.tla b/spec/light-client/verification/MC7_7_faulty.tla similarity index 100% rename from rust-spec/lightclient/verification/MC7_7_faulty.tla rename to spec/light-client/verification/MC7_7_faulty.tla diff --git a/spec/light-client/verification.md b/spec/light-client/verification/README.md similarity index 99% rename from spec/light-client/verification.md rename to spec/light-client/verification/README.md index 9166923e844..8777374ac99 100644 --- a/spec/light-client/verification.md +++ b/spec/light-client/verification/README.md @@ -1,3 +1,9 @@ +--- +order: 1 +parent: + title: Verification + order: 2 +--- # Core Verification ## Problem statement diff --git a/rust-spec/lightclient/verification/verification_001_published.md b/spec/light-client/verification/verification_001_published.md similarity index 99% rename from rust-spec/lightclient/verification/verification_001_published.md rename to spec/light-client/verification/verification_001_published.md index 05baedb3f6d..0a63803d78e 100644 --- a/rust-spec/lightclient/verification/verification_001_published.md +++ b/spec/light-client/verification/verification_001_published.md @@ -502,7 +502,6 @@ const ( ) ``` - > Only the detector module sets a lightBlock state to `StateTrusted` > and only if it was `StateVerified` before. @@ -533,12 +532,12 @@ func (ls LightStore) LatestVerified() LightBlock ```go func (ls LightStore) Update(lightBlock LightBlock, verfiedState VerifiedState - verifiedBy Height) + verifiedBy Height) ``` - Expected postcondition - The state of the LightBlock is set to *verifiedState*. - - verifiedBy of the Lightblock is set to *Height* + - verifiedBy of the Lightblock is set to *Height* > The following function is used only in the detector specification > listed here for completeness. diff --git a/rust-spec/lightclient/verification/verification_002_draft.md b/spec/light-client/verification/verification_002_draft.md similarity index 99% rename from rust-spec/lightclient/verification/verification_002_draft.md rename to spec/light-client/verification/verification_002_draft.md index 08bf0a80738..e502880bb70 100644 --- a/rust-spec/lightclient/verification/verification_002_draft.md +++ b/spec/light-client/verification/verification_002_draft.md @@ -523,7 +523,9 @@ then The LightStore exposes the following functions to query stored LightBlocks. #### **[LCV-DATA-LS-STATE.1]** + Each LightBlock is in one of the following states: + ```go type VerifiedState int @@ -555,15 +557,16 @@ func (ls LightStore) Latest() LightBlock - returns the highest light block #### **[LCV-FUNC-ADD.1]** + ```go func (ls LightStore) Add(newBlock) ``` + - Expected precondition - the lightstore is empty - Expected postcondition - adds newBlock into light store - - + #### **[LCV-FUNC-STORE.1]** ```go @@ -573,8 +576,6 @@ func (ls LightStore) store_chain(newLS LightStore) - Expected postcondition - adds `newLS` to the lightStore. - - #### **[LCV-FUNC-LATEST-VERIF.2]** ```go @@ -605,18 +606,16 @@ VerifiedState, root-height Height) - The state of the LightBlock is set to *verifiedState*. - The verification-root of the LightBlock is set to *root-height* - ```go func (ls LightStore) TraceTo(lightBlock LightBlock) (LightBlock, LightStore) ``` + - Expected postcondition - returns a **trusted** lightblock `root` from the lightstore with a height less than `lightBlock` - - returns a lightstore that contains lightblocks that constitute a + - returns a lightstore that contains lightblocks that constitute a [verification trace](TODOlinkToDetectorSpecOnceThere) from `root` to `lightBlock` (including `lightBlock`) - - ### Inputs @@ -690,7 +689,7 @@ func Commit(height int64) (SignedHeader, error) - if *n* is correct: precondition violated or timeout - if *n* is faulty: arbitrary error ----- +----; ```go func Validators(height int64) (ValidatorSet, error) @@ -722,7 +721,7 @@ func Validators(height int64) (ValidatorSet, error) - if *n* is correct: precondition violated or timeout - if *n* is faulty: arbitrary error ----- +----; ### Communicating Function @@ -753,7 +752,7 @@ func FetchLightBlock(peer PeerID, height Height) LightBlock - if *lb.provider != peer* - times out after 2 Delta (by assumption *n* is faulty) ----- +----; ## Core Verification @@ -875,7 +874,7 @@ func ValidAndVerified(trusted LightBlock, untrusted LightBlock) Result - Error condition: - if precondition violated ----- +----; #### **[LCV-FUNC-SCHEDULE.1]** @@ -958,16 +957,19 @@ func (ls LightStore) LatestPrevious(height Height) (LightBlock, bool) holds *lb.Header.Height >= b.Header.Height* - *false* in the second argument if the LightStore does not contain such an *lb*. ---- + +----; #### **[LCV-FUNC-LOWEST.2]** ```go func (ls LightStore) Lowest() (LightBlock) ``` + - Expected postcondition - returns the lowest trusted light block within trusting period ---- + +----; #### **[LCV-FUNC-MIN.2]**