diff --git a/docs/architecture/adr-046-light-client-implementation.md b/docs/architecture/adr-046-light-client-implementation.md index dca1c6692..6058da8f8 100644 --- a/docs/architecture/adr-046-light-client-implementation.md +++ b/docs/architecture/adr-046-light-client-implementation.md @@ -3,6 +3,7 @@ ## Changelog * 13-02-2020: Initial draft * 26-02-2020: Cross-checking the first header +* 28-02-2020: Bisection algorithm details ## Context @@ -67,9 +68,13 @@ required to respond: 1. Note the very first header (`TrustOptions.Hash`) is also cross-checked with witnesses for additional security. Due to bisection algorithm nature, some headers might be skipped. If the light -client does not have a header for height `X` and `TrustedHeader(X)` or -`TrustedValidatorSet(X)` methods are called, it will download the header from -primary provider and perform a backwards verification. +client does not have a header for height `X` and `VerifyHeaderAtHeight(X)` or +`VerifyHeader(H#X)` methods are called, it will perform a backwards +verification from the latest header back to the header at height `X`. + +`TrustedHeader`, `TrustedValidatorSet` only communicate with the trusted store. +If some header is not there, an error will be returned indicating that +verification is required. ```go type Provider interface { @@ -127,6 +132,21 @@ cases of adjacent and non-adjacent headers. In the former case, it compares the hashes directly (2/3+ signed transition). Otherwise, it verifies 1/3+ (`trustLevel`) of trusted validators are still present in new validators. +### Bisection algorithm details + +Non-recursive bisection algorithm was implemented despite the spec containing +the recursive version. There are two major reasons: + +1) Constant memory consumption => no risk of getting OOM (Out-Of-Memory) exceptions; +2) Faster finality (see Fig. 1). + +_Fig. 1: Differences between recursive and non-recursive bisections_ + +![Fig. 1](./img/adr-046-fig1.png) + +Specification of the non-recursive bisection can be found +[here](https://github.com/tendermint/spec/blob/zm_non-recursive-verification/spec/consensus/light-client/non-recursive-verification.md). + ## Status Accepted. diff --git a/docs/architecture/img/adr-046-fig1.png b/docs/architecture/img/adr-046-fig1.png new file mode 100644 index 000000000..d68712e8a Binary files /dev/null and b/docs/architecture/img/adr-046-fig1.png differ