mirrors/tendermint
1
0
Fork 0
mirror of https://github.com/tendermint/tendermint.git synced 2026-05-23 23:51:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Separating algorithm from proofs

Browse Source
This commit is contained in:
Zarko Milosevic
2019-12-26 13:11:01 +01:00
parent ee0cc537b8
commit 0adde9d415
1 changed files with 323 additions and 294 deletions
Download Patch File Download Diff File Expand all files Collapse all files

617
spec/consensus/light-client.md
View File

@@ -1,24 +1,16 @@
# Lite client
A lite client is a process that connects to Tendermint full nodes and then tries to verify application data using the Merkle proofs.
## Context of this document
In order to make sure that full nodes have the incentive to follow the protocol, we have to address the following three Issues
1) The lite client needs a method to verify headers it obtains from a full node it connects to according to trust assumptions -- this document.
2) The lite client must be able to connect to other full nodes to detect and report on failures in the trust assumptions (i.e., conflicting headers) -- a future document (see #4215).
3) In the event the trust assumption fails (i.e., a lite client is fooled by a conflicting header), the Tendermint fork accountability protocol must account for the evidence -- a future document (see #3840).
A lite client is a process that connects to Tendermint full node(s) and then tries to verify application
data using the Merkle proofs.
## Problem statement
We assume that the lite client knows a (base) header *inithead* it trusts (by social consensus or because
the lite client has decided to trust the header before). The goal is to check whether another header
*newhead* can be trusted based on the data in *inithead*.
We assume that the lite client knows a (base) header *inithead* it trusts (by social consensus or because the lite client has decided to trust the header before). The goal is to check whether another header *newhead* can be trusted based on the data in *inithead*.
The correctness of the protocol is based on the assumption that *inithead* was generated by an instance of Tendermint consensus. The term "trusting" above indicates that the correctness of the protocol depends on this assumption. It is in the responsibility of the user that runs the lite client to make sure that the risk of trusting a corrupted/forged *inithead* is negligible.
The correctness of the protocol is based on the assumption that *inithead* was generated by an instance of
Tendermint consensus.
## Definitions
@@ -26,63 +18,340 @@ The correctness of the protocol is based on the assumption that *inithead* was g
In the following, only the details of the data structures needed for this specification are given.
* header fields
- *Height*
- *Time*: the chain time when the header (block) was generated
- *ValidatorsHash*: hash of the validators for the current block
- *NextValidatorsHash*: hash of the validators for the next block
- *LastCommitHash*: hash commit from validators from the last block
- *commit*: evidence that block with height *height* - 1 was committed by a set of validators (canonical commit).
We will use ```signers(commit)``` to refer to the set of validators that committed the block.
```go
type Header struct {
Height int64
Time Time // the chain time when the header (block) was generated
* signed header fields: contains a header and a *commit* for the current header; a "seen commit".
In Tendermint consensus the "canonical commit" is stored in header *height* + 1.
// hashes from the app output from the prev block
ValidatorsHash []byte // hash of the validators for the current block
NextValidatorsHash []byte // hash of the validators for the next block
* For each header *h* it has locally stored, the lite client stores whether
it trusts *h*. We write *trust(h) = true*, if this is the case.
// hashes of block data
LastCommitHash []byte // hash of the commit from validators from the last block
...
}
* Validator fields. We will write a validator as a tuple *(v,p)* such that
+ *v* is the identifier (we assume identifiers are unique in each validator set)
+ *p* is its voting power
type SignedHeader struct {
Header Header
Commit Commit // commit for the given header
}
type ValidatorSet struct {
Validators []Validator
}
type Validator struct {
Address Address // validator address (we assume validator's addresses are unique)
VotingPower int64 // validator's voting power
}
```
### Functions
For the purpose of this lite client specification, we assume that the Tendermint Full Node exposes the following functions over Tendermint RPC:
```go
// returns signed header: header (with the fields from above) with Commit
// that include signatures of validators that signed the header
// returns signed header: Header with Commit
func Commit(height int64) (SignedHeader, error)
// returns validator set for the given height
func Validators(height int64) (ValidatorSet, error)
type SignedHeader struct {
Header Header
Commit Commit
}
type ValidatorSet struct {
Validators []Validator
}
type Validator struct {
Address Address
VotingPower int64
}
```
Furthermore, we assume the following auxiliary functions:
```go
// returns the validator set for the given validator hash
func validators(validatorsHash []byte) ValidatorSet
// TODO: define precisely what this functions is supposed to be doing
func signers(commit) []Validator
// returns the set of validators from the given validator set that committed the block
func signers(commit Commit, validatorSet ValidatorSet) []Validator
```
### Tendermint Failure Model
If a block `b` is generated at time `Time` (and this time is stored in the block), then a set of validators that
hold more than 2/3 of the voting power in `validators(b.Header.NextValidatorsHash)` is correct until time
`b.Header.Time + TRUSTED_PERIOD`.
*Assumption*: "correct" is defined w.r.t. realtime (some Newtonian global notion of time, i.e., wall time),
while `Header.Time` corresponds to the [BFT time](bft-time.md). In this note, we assume that clocks of correct processes
are synchronized (for example using NTP), and therefore there is bounded clock drift between clocks and
BFT time. We can make this more precise eventually (incorporating clock drift, accuracy, precision, etc.). Right now,
we consider this assumption sufficient, as clock synchronization (under NTP) is in the order of milliseconds and
`TRUSTED_PERIOD` is in the order of weeks.
*Remark*: This failure model might change to a hybrid version that takes heights into account in the future.
The specification in this document considers an implementation of the lite client under the Tendermint Failure Model. Issues
like `counter-factual signing`, `fork accountability` and `evidence submission` are mechanisms that justify this assumption by
incentivizing validators to follow the protocol. If they don't, and we have 1/3 (or more) faults, safety may be violated.
Our approach then is to *detect* these cases (after the fact), and take suitable repair actions (automatic and social).
This is discussed in document on [Fork accountability](fork-accountability.md).
### Functions
**VerifyHeader.** The function `VerifyHeader` captures high level logic, i.e., application call to the lite client module to (optionally download) and
verify header for some height. The core verification logic is captured by `CanTrust` function that iteratively try to establish trust in given header
by relying on `CheckSupport` function.
```go
func VerifyHeader(height, trustThreshold) error {
if untrusted_h, exists := Store.Get(height); exists {
if isWithinTrustedPeriod(untrusted_h) return nil
return ErrHeaderNotWithinTrustedPeriod(untrusted_h)
}
untrusted_h := Commit(height)
if !verify(untrusted_h) { return ErrInvalidHeader(untrusted_h) }
if !isWithinTrustedPeriod(untrusted_h) { return ErrHeaderNotWithinTrustedPeriod(untrusted_h) }
// get the highest trusted headers lower than untrusted_h
trusted_h = Store.HighestTrustedSmallerThan(height)
if trusted_h == nil { return ErrNoTrustedHeader }
err = CanTrust(trusted_h, untrusted_h, trustThreshold) // or CanTrustBisection((trusted_h, untrusted_h, trustThreshold)
if err != nil { return err }
if isWithinTrustedPeriod(untrusted_h) {
Store.add(untrusted_h)
// we store only trusted headers, as we assume that only trusted headers
// are influencing end user business decisions.
return nil
}
return ErrHeaderNotTrusted(untrusted_h)
}
```
The function `CanTrust` checks whether to trust header `untrusted_h` based on the trusted header `trusted_h` It does so by (potentially)
building transitive trust relation between `trusted_h` and `untrusted_h`, over some intermediate headers. For example, in case we cannot trust
header `untrusted_h` based on the trusted header `trusted_h`, the function `CanTrust` will try to find headers such that we can transition trust
from `trusted_h` over intermediate headers to `untrusted_h`. We will give two implementations of `CanTrust`, the one based
on bisection that is recursive and the other that is non-recursive. We give two implementations as recursive version might be easier
to understand but non-recursive version might be simpler to formally express and verify using TLA+/TLC.
Both implementations of `CanTrust` function are based on `CheckSupport` function that implements the skipping conditions under which we can trust a
header `untrusted_h` given the trust in the header `trusted_h` as a single step,
i.e., it does not assume ensuring transitive trust relation between headers through some intermediate headers.
```go
// return nil in case we can trust header untrusted_h based on header trusted_h; otherwise return error
// where error captures the nature of the error.
// Note that untrusted_h must have been verified by the caller, i.e. verify(untrusted_h) was successful.
func CanTrust(trusted_h,untrusted_h,trustThreshold) error {
assume trusted_h.Header.Height < untrusted_h.header.Height
th := trusted_h // th is trusted header
// untrustedHeader is a list of verified headers that have not passed CheckSupport()
untrustedHeaders := [untrusted_h]
while true {
for h in untrustedHeaders {
// we assume here that iteration is done in the order of header heights
err = CheckSupport(th,h,trustThreshold)
if err == nil {
th = h
Store.Add(h)
untrustedHeaders.RemoveHeadersSmallerOrEqual(h.Header.Height)
if th == untrusted_h { return nil }
}
if (err != ErrTooMuchChange) { return err }
}
endHeight = min(untrustedHeaders)
foundPivot = false
while(!foundPivot) {
pivot := (th.Header.height + endHeight) / 2
hp := Commit(pivot)
if !verify(hp) { return ErrInvalidHeader(hp) }
// try to move trusted header forward to hp
err = CheckSupport(th,hp,trustThreshold)
if (err != nil and err != ErrTooMuchChange) return err
if err == nil {
th = hp
Store.Add(hp)
foundPivot = true
}
untrustedHeaders.add(hp)
endHeight = pivot
}
}
return nil // this line should never be reached
}
```
```go
func CanTrustBisection(trusted_h,untrusted_h,trustThreshold) error {
assume trusted_h.Header.Height < untrusted_h.header.Height
err = CheckSupport(trusted_h,untrusted_h,trustThreshold)
if err == nil {
Store.Add(untrusted_h)
return nil
}
if err != ErrTooMuchChange return err
pivot := (trusted_h.Header.height + untrusted_h.Header.height) / 2
hp := Commit(pivot)
if !verify(hp) return ErrInvalidHeader(hp)
err = CanTrustBisection(trusted_h,hp,trustThreshold)
if err == nil {
Store.Add(hp)
err2 = CanTrustBisection(hp,untrusted_h,trustThreshold)
if err2 == nil {
Store.Add(untrusted_h)
return nil
}
return err2
}
return err
}
```
**Auxiliary Functions.** We will use the function ```votingPowerIn(V1,V2)``` to compute the voting power the validators in set V1 have according to their voting power in set V2;
we will write ```totalVotingPower(V)``` for ```votingPowerIn(V,V)```, which returns the total voting power in V.
We further use the function ```signers(Commit)``` that returns the set of validators that signed the Commit.
**CheckSupport.** The following function defines skipping condition under the Tendermint Failure model, i.e., it defines when we can trust the header untrusted_h based on header trusted_h.
Time validity of a header is captured by the ```isWithinTrustedPeriod``` function that depends on lite client trusted period (`LITE_CLIENT_TRUSTED_PERIOD`) and it returns
true in case the header is within its lite client trusted period.
```verify``` function is capturing basic header verification, i.e., it ensures that the header is signed by more than 2/3 of the voting power of the corresponding validator set.
```go
// return true if header is within its lite client trusted period; otherwise it returns false
func isWithinTrustedPeriod(h, now) bool {
return h.Header.bfttime + LITE_CLIENT_TRUSTED_PERIOD > now
}
// return true if header is correctly signed by 2/3+ voting power in the corresponding
// validator set; otherwise false. Additional checks should be done in the implementation
// to ensure header is well formed.
func verify(h) bool {
vp_all := totalVotingPower(h.Header.V) // total sum of voting power of validators in h
return votingPowerIn(signers(h.Commit),h.Header.V) > 2/3 * vp_all
}
// Captures skipping condition. trusted_h and untrusted_h have already passed basic validation
// (function `verify`).
// Returns nil in case untrusted_h can be trusted based on trusted_h, otherwise returns error.
// ErrHeaderNotWithinTrustedPeriod is used when trusted_h has expired with respect to lite client trusted period,
// ErrInvalidAdjacentHeaders when that adjacent headers are not consistent and
// ErrTooMuchChange when there is not enough intersection between validator sets to have
// skipping condition true.
func CheckSupport(trusted_h,untrusted_h,trustThreshold) error {
assert trusted_h.Header.Height < untrusted_h.header.Height and
trusted_h.Header.bfttime < untrusted_h.Header.bfttime and
untrusted_h.Header.bfttime < now
if !isWithinTrustedPeriod(trusted_h) return ErrHeaderNotWithinTrustedPeriod(trusted_h)
// Although while executing the rest of CheckSupport function, trusted_h can expire based
// on the lite client trusted period, this is not problem as lite client trusted
// period is smaller than trusted period of the header based on Tendermint Failure
// model, i.e., there is a significant time period (measure in days) during which
// validator set that has signed trusted_h can be trusted. Furthermore, CheckSupport function
// is not doing expensive operation (neither rpc nor signature verification), so it
// should execute fast.
// check for adjacent headers
if untrusted_h.Header.height == trusted_h.Header.height + 1 {
if trusted_h.Header.NextV == untrusted_h.Header.V
return nil
return ErrInvalidAdjacentHeaders
}
// total sum of voting power of validators in trusted_h.NextV
vp_all := totalVotingPower(trusted_h.Header.NextV)
// check for non-adjacent headers
if votingPowerIn(signers(untrusted_h.Commit),trusted_h.Header.NextV) > max(1/3,trustThreshold) * vp_all {
return nil
}
return ErrTooMuchChange
}
```
### The case `untrusted_h.Header.height < trusted_h.Header.height`
In the use case where someone tells the lite client that application data that is relevant for it
can be read in the block of height `k` and the lite client trusts a more recent header, we can use the
hashes to verify headers "down the chain." That is, we iterate down the heights and check the hashes in each step.
*Remark.* For the case were the lite client trusts two headers `i` and `j` with `i < k < j`, we should
discuss/experiment whether the forward or the backward method is more effective.
```go
func Backwards(trusted_h,untrusted_h) error {
assert (untrusted_h.Header.height < trusted_h.Header.height)
if !isWithinTrustedPeriod(trusted_h) return ErrHeaderNotTrusted(trusted_h)
old := trusted_h
for i := trusted_h.Header.height - 1; i > untrusted_h.Header.height; i-- {
new := Commit(i)
if (hash(new) != old.Header.hash) {
return ErrInvalidAdjacentHeaders
}
old := new
if !isWithinTrustedPeriod(trusted_h) return ErrHeaderNotTrusted(trusted_h)
}
if hash(untrusted_h) != old.Header.hash return ErrInvalidAdjacentHeaders
return nil
}
```
In order to incentivize correct behavior of validators that run Tendermint consensus protocol, fork detection protocol (it will be explained in different document) is executed in case of a fork (conflicting
headers are detected). As detecting conflicting headers, its propagation through the network (by the gossip protocol) and execution of the fork accountability
protocol on the chain takes time, the lite client logic assumes conservative value for trusted period. More precisely, in the context of lite client we always
operate with a smaller trusted period that we call *lite client trusted period* (LITE_CLIENT_TRUSTED_PERIOD). If we assume that upper bound
for fork detection, propagation and processing on the chain is denoted with *fork procession period* (FORK_PROCESSING_PERIOD), then the following formula
holds:
```LITE_CLIENT_TRUSTED_PERIOD + FORK_PROCESSING_PERIOD < TRUSTED_PERIOD```, where TRUSTED_PERIOD comes from the Tendermint Failure Model.
*Assumption*: In the following, we assume that *untrusted_h.Header.height > trusted_h.Header.height*. We will quickly discuss the other case in the next section.
We consider the following set-up:
- the lite client communicates with one full node
- the lite client locally stores all the headers that has passed basic verification and that are within lite client trust period. In the pseudo code below we
write *Store.Add(header)* for this. If a header failed to verify, then
the full node we are talking to is faulty and we should disconnect from it and reinitialise with new peer.
- If `CanTrust` returns *error*, then the lite client has seen a forged header or the trusted header has expired (it is outside its trusted period).
* In case of forged header, the full node is faulty so lite client should disconnect and reinitialise with new peer. If the trusted header has expired,
we need to reinitialise lite client with new trusted header (that is within its trusted period), but we don't necessarily need to disconnect from the full node
we are talking to (as we haven't observed full node misbehavior in this case).
## Context of this document
In order to make sure that full nodes have the incentive to follow the protocol, we have to address the
following three Issues
1) The lite client needs a method to verify headers it obtains from a full node it connects to according to trust assumptions -- this document.
2) The lite client must be able to connect to other full nodes to detect and report on failures in the trust assumptions (i.e., conflicting headers) -- a future document (see #4215).
3) In the event the trust assumption fails (i.e., a lite client is fooled by a conflicting header), the Tendermint fork accountability protocol must account for the evidence -- a future document (see #3840).
The term "trusting" above indicates that the correctness of the protocol depends on
this assumption. It is in the responsibility of the user that runs the lite client to make sure that the risk
of trusting a corrupted/forged *inithead* is negligible.
* For each header *h* it has locally stored, the lite client stores whether
it trusts *h*. We write *trust(h) = true*, if this is the case.
* signed header fields: contains a header and a *commit* for the current header; a "seen commit".
In Tendermint consensus the "canonical commit" is stored in header *height* + 1.
* Validator fields. We will write a validator as a tuple *(v,p)* such that
+ *v* is the identifier (we assume identifiers are unique in each validator set)
+ *p* is its voting power
### Definitions
@@ -91,8 +360,6 @@ Furthermore, we assume the following auxiliary functions:
follows the protocol until time *t* (we will see about recovery later).
### Tendermint Failure Model
If a block *b* is generated at time *Time* (and this time is stored in the block), then a set of validators that
@@ -105,17 +372,6 @@ Formally,
2/3 \sum_{(v,p) \in h.Header.NextV} p
\]
*Assumption*: "correct" is defined w.r.t. realtime (some Newtonian global notion of time, i.e., wall time), while *bfttime* corresponds to the reading of the local clock of a validator (how this time is computed may change when the Tendermint consensus is modified). In this note, we assume that all clocks are synchronized to realtime. We can make this more precise eventually (incorporating clock drift, accuracy, precision, etc.). Right now, we consider this assumption sufficient, as clock synchronization (under NTP) is in the order of milliseconds and *tp* is in the order of weeks.
*Remark*: This failure model might change to a hybrid version that takes heights into account in the future.
The specification in this document considers an implementation of the lite client under the Tendermint Failure Model. Issues
like *counter-factual signing* and *fork accountability* and *evidence submission* are mechanisms that justify this assumption by
incentivizing validators to follow the protocol. If they don't, and we have more that 1/3 faults, safety may be violated.
Our approach then is to *detect* these cases (after the fact), and take suitable repair actions (automatic and social).
This is discussed in an upcoming document on "Fork accountability". (These safety violations include the lite client wrongly
trusting a header, a fork in the blockchain, etc.)
## Lite Client Trusting Spec
@@ -192,234 +448,31 @@ When we say we trust *h.Header.NextV* we do *not* trust that each individual val
but we only trust the fact that less than 1/3 of them are faulty (more precisely, the faulty ones have less than 1/3 of the total voting power).
### Functions
The function *CanTrust* checks whether to trust header *untrusted_h* based on the trusted header *trusted_h*. It does so by (potentially)
building transitive trust relation between *trusted_h* and *untrusted_h*, over some intermediate headers. For example, in case we cannot trust
header *untrusted_h* based on the trusted header *trusted_h*, the function *CanTrust* will try to find headers such that we can transition trust
from *trusted_h* over intermediate headers to *untrusted_h*. We will give two implementations of *CanTrust*, the one based
on bisection that is recursive and the other that is non-recursive. We give two implementations as recursive version might be easier
to understand but non-recursive version might be simpler to formally express and verify using TLA+/TLC.
Both implementations of *CanTrust* function are based on *CheckSupport* function that implements the skipping conditions under which we can trust a
header *untrusted_h* given the trust in the header *trusted_h* as a single step,
i.e., it does not assume ensuring transitive trust relation between headers through some intermediate headers.
In order to incentivize correct behavior of validators that run Tendermint consensus protocol, fork detection protocol (it will be explained in different document) is executed in case of a fork (conflicting
headers are detected). As detecting conflicting headers, its propagation through the network (by the gossip protocol) and execution of the fork accountability
protocol on the chain takes time, the lite client logic assumes conservative value for trusted period. More precisely, in the context of lite client we always
operate with a smaller trusted period that we call *lite client trusted period* (LITE_CLIENT_TRUSTED_PERIOD). If we assume that upper bound
for fork detection, propagation and processing on the chain is denoted with *fork procession period* (FORK_PROCESSING_PERIOD), then the following formula
holds:
```LITE_CLIENT_TRUSTED_PERIOD + FORK_PROCESSING_PERIOD < TRUSTED_PERIOD```, where TRUSTED_PERIOD comes from the Tendermint Failure Model.
*Assumption*: In the following, we assume that *untrusted_h.Header.height > trusted_h.Header.height*. We will quickly discuss the other case in the next section.
We consider the following set-up:
- the lite client communicates with one full node
- the lite client locally stores all the headers that has passed basic verification and that are within lite client trust period. In the pseudo code below we
write *Store.Add(header)* for this. If a header failed to verify, then
the full node we are talking to is faulty and we should disconnect from it and reinitialise with new peer.
- If *CanTrust* returns *error*, then the lite client has seen a forged header or the trusted header has expired (it is outside its trusted period).
* In case of forged header, the full node is faulty so lite client should disconnect and reinitialise with new peer. If the trusted header has expired,
we need to reinitialise lite client with new trusted header (that is within its trusted period), but we don't necessarily need to disconnect from the full node
we are talking to (as we haven't observed full node misbehavior in this case).
**Auxiliary Functions.** We will use the function ```votingPowerIn(V1,V2)``` to compute the voting power the validators in set V1 have according to their voting power in set V2;
we will write ```totalVotingPower(V)``` for ```votingPowerIn(V,V)```, which returns the total voting power in V.
We further use the function ```signers(Commit)``` that returns the set of validators that signed the Commit.
**CheckSupport.** The following function defines skipping condition under the Tendermint Failure model, i.e., it defines when we can trust the header untrusted_h based on header trusted_h.
Time validity of a header is captured by the ```isWithinTrustedPeriod``` function that depends on lite client trusted period (`LITE_CLIENT_TRUSTED_PERIOD`) and it returns
true in case the header is within its lite client trusted period.
```verify``` function is capturing basic header verification, i.e., it ensures that the header is signed by more than 2/3 of the voting power of the corresponding validator set.
```go
// return true if header is within its lite client trusted period; otherwise it returns false
func isWithinTrustedPeriod(h, now) bool {
return h.Header.bfttime + LITE_CLIENT_TRUSTED_PERIOD > now
}
// return true if header is correctly signed by 2/3+ voting power in the corresponding
// validator set; otherwise false. Additional checks should be done in the implementation
// to ensure header is well formed.
func verify(h) bool {
vp_all := totalVotingPower(h.Header.V) // total sum of voting power of validators in h
return votingPowerIn(signers(h.Commit),h.Header.V) > 2/3 * vp_all
}
// Captures skipping condition. trusted_h and untrusted_h have already passed basic validation
// (function `verify`).
// Returns nil in case untrusted_h can be trusted based on trusted_h, otherwise returns error.
// ErrHeaderNotWithinTrustedPeriod is used when trusted_h has expired with respect to lite client trusted period,
// ErrInvalidAdjacentHeaders when that adjacent headers are not consistent and
// ErrTooMuchChange when there is not enough intersection between validator sets to have
// skipping condition true.
func CheckSupport(trusted_h,untrusted_h,trustThreshold) error {
assert trusted_h.Header.Height < untrusted_h.header.Height and
trusted_h.Header.bfttime < untrusted_h.Header.bfttime and
untrusted_h.Header.bfttime < now
if !isWithinTrustedPeriod(trusted_h) return ErrHeaderNotWithinTrustedPeriod(trusted_h)
// Although while executing the rest of CheckSupport function, trusted_h can expire based
// on the lite client trusted period, this is not problem as lite client trusted
// period is smaller than trusted period of the header based on Tendermint Failure
// model, i.e., there is a significant time period (measure in days) during which
// validator set that has signed trusted_h can be trusted. Furthermore, CheckSupport function
// is not doing expensive operation (neither rpc nor signature verification), so it
// should execute fast.
// check for adjacent headers
if untrusted_h.Header.height == trusted_h.Header.height + 1 {
if trusted_h.Header.NextV == untrusted_h.Header.V
return nil
return ErrInvalidAdjacentHeaders
}
// total sum of voting power of validators in trusted_h.NextV
vp_all := totalVotingPower(trusted_h.Header.NextV)
// check for non-adjacent headers
if votingPowerIn(signers(untrusted_h.Commit),trusted_h.Header.NextV) > max(1/3,trustThreshold) * vp_all {
return nil
}
return ErrTooMuchChange
}
```
*Correctness arguments*
Towards Lite Client Accuracy:
- Assume by contradiction that *untrusted_h* was not generated correctly and the lite client sets trust to true because *CheckSupport* returns true.
- Assume by contradiction that `untrusted_h` was not generated correctly and the lite client sets trust to true because `CheckSupport` returns true.
- trusted_h is trusted and sufficiently new
- by Tendermint Fault Model, less than 1/3 of voting power held by faulty validators => at least one correct validator *v* has signed *untrusted_h*.
- as *v* is correct up to now, it followed the Tendermint consensus protocol at least up to signing *untrusted_h* => *untrusted_h* was correctly generated, we arrive at the required contradiction.
- by Tendermint Fault Model, less than 1/3 of voting power held by faulty validators => at least one correct validator *v* has signed `untrusted_h`.
- as *v* is correct up to now, it followed the Tendermint consensus protocol at least up to signing `untrusted_h` => `untrusted_h` was correctly generated, we arrive at the required contradiction.
Towards Lite Client Completeness:
- The check is successful if sufficiently many validators of *trusted_h* are still validators in *untrusted_h* and signed *untrusted_h*.
- The check is successful if sufficiently many validators of `trusted_h` are still validators in `untrusted_h` and signed `untrusted_h`.
- If *untrusted_h.Header.height = trusted_h.Header.height + 1*, and both headers were generated correctly, the test passes
*Verification Condition:* We may need a Tendermint invariant stating that if *untrusted_h.Header.height = trusted_h.Header.height + 1* then *signers(untrusted_h.Commit) \subseteq trusted_h.Header.NextV*.
*Remark*: The variable *trustThreshold* can be used if the user believes that relying on one correct validator is not sufficient. However, in case of (frequent) changes in the validator set, the higher the *trustThreshold* is chosen, the more unlikely it becomes that CheckSupport returns true for non-adjacent headers.
**VerifyHeader.** The function *VerifyHeader* captures high level logic, i.e., application call to the lite client module to (optionally download) and
verify header for some height. The core verification logic is captured by *CanTrust* function that iteratively try to establish trust in given header
by relying on *CheckSupport* function.
```go
func VerifyHeader(height, trustThreshold) error {
if untrusted_h, exists := Store.Get(height); exists {
if isWithinTrustedPeriod(untrusted_h) return nil
return ErrHeaderNotWithinTrustedPeriod(untrusted_h)
}
untrusted_h := Commit(height)
if !verify(untrusted_h) { return ErrInvalidHeader(untrusted_h) }
if !isWithinTrustedPeriod(untrusted_h) { return ErrHeaderNotWithinTrustedPeriod(untrusted_h) }
// get the highest trusted headers lower than untrusted_h
trusted_h = Store.HighestTrustedSmallerThan(height)
if trusted_h == nil { return ErrNoTrustedHeader }
err = CanTrust(trusted_h, untrusted_h, trustThreshold) // or CanTrustBisection((trusted_h, untrusted_h, trustThreshold)
if err != nil { return err }
if isWithinTrustedPeriod(untrusted_h) {
Store.add(untrusted_h)
// we store only trusted headers, as we assume that only trusted headers
// are influencing end user business decisions.
return nil
}
return ErrHeaderNotTrusted(untrusted_h)
}
// return nil in case we can trust header untrusted_h based on header trusted_h; otherwise return error
// where error captures the nature of the error.
// Note that untrusted_h must have been verified by the caller, i.e. verify(untrusted_h) was successful.
func CanTrust(trusted_h,untrusted_h,trustThreshold) error {
assume trusted_h.Header.Height < untrusted_h.header.Height
th := trusted_h // th is trusted header
// untrustedHeader is a list of verified headers that have not passed CheckSupport()
untrustedHeaders := [untrusted_h]
while true {
for h in untrustedHeaders {
// we assume here that iteration is done in the order of header heights
err = CheckSupport(th,h,trustThreshold)
if err == nil {
th = h
Store.Add(h)
untrustedHeaders.RemoveHeadersSmallerOrEqual(h.Header.Height)
if th == untrusted_h { return nil }
}
if (err != ErrTooMuchChange) { return err }
}
endHeight = min(untrustedHeaders)
foundPivot = false
while(!foundPivot) {
pivot := (th.Header.height + endHeight) / 2
hp := Commit(pivot)
if !verify(hp) { return ErrInvalidHeader(hp) }
// try to move trusted header forward to hp
err = CheckSupport(th,hp,trustThreshold)
if (err != nil and err != ErrTooMuchChange) return err
if err == nil {
th = hp
Store.Add(hp)
foundPivot = true
}
untrustedHeaders.add(hp)
endHeight = pivot
}
}
return nil // this line should never be reached
}
```
```go
func CanTrustBisection(trusted_h,untrusted_h,trustThreshold) error {
assume trusted_h.Header.Height < untrusted_h.header.Height
err = CheckSupport(trusted_h,untrusted_h,trustThreshold)
if err == nil {
Store.Add(untrusted_h)
return nil
}
if err != ErrTooMuchChange return err
pivot := (trusted_h.Header.height + untrusted_h.Header.height) / 2
hp := Commit(pivot)
if !verify(hp) return ErrInvalidHeader(hp)
err = CanTrustBisection(trusted_h,hp,trustThreshold)
if err == nil {
Store.Add(hp)
err2 = CanTrustBisection(hp,untrusted_h,trustThreshold)
if err2 == nil {
Store.Add(untrusted_h)
return nil
}
return err2
}
return err
}
```
*Correctness arguments (sketch)*
Lite Client Accuracy:
- Assume by contradiction that *untrusted_h* was not generated correctly and the lite client sets trust to true because CanTrustBisection returns nil.
- Assume by contradiction that `untrusted_h` was not generated correctly and the lite client sets trust to true because CanTrustBisection returns nil.
- CanTrustBisection returns true only if all calls to CheckSupport in the recursion return nil.
- Thus we have a sequence of headers that all satisfied the CheckSupport
- again a contradiction
@@ -436,30 +489,6 @@ With CanTrustBisection, a faulty full node could stall a lite client by creating
* We may set a timeout how long bisection may take.
### The case *untrusted_h.Header.height < trusted_h.Header.height*
In the use case where someone tells the lite client that application data that is relevant for it can be read in the block of height *k* and the lite client trusts a more recent header, we can use the hashes to verify headers "down the chain." That is, we iterate down the heights and check the hashes in each step.
*Remark.* For the case were the lite client trusts two headers *i* and *j* with *i < k < j*, we should discuss/experiment whether the forward or the backward method is more effective.
```go
func Backwards(trusted_h,untrusted_h) error {
assert (untrusted_h.Header.height < trusted_h.Header.height)
if !isWithinTrustedPeriod(trusted_h) return ErrHeaderNotTrusted(trusted_h)
old := trusted_h
for i := trusted_h.Header.height - 1; i > untrusted_h.Header.height; i-- {
new := Commit(i)
if (hash(new) != old.Header.hash) {
return ErrInvalidAdjacentHeaders
}
old := new
if !isWithinTrustedPeriod(trusted_h) return ErrHeaderNotTrusted(trusted_h)
}
if hash(untrusted_h) != old.Header.hash return ErrInvalidAdjacentHeaders
return nil
}
```