A lite client is a process that connects to Tendermint full nodes and then tries to verify application data using the Merkle proofs.
In order to make sure that full nodes have the incentive to follow the protocol, we have to address the following three Issues
The lite client needs a method to verify headers it obtains from a full node it connects to according to trust assumptions -- this document.
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).
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).
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.
In the following, only the details of the data structures needed for this specification are given.
header fields
signers(commit)
to refer to the set of validators that committed the block.signed header fields: contains a header and a commit for the current header; a "seen commit". In the Tendermint consensus the "canonical commit" is stored in header height + 1.
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.
Validator fields. We will write a validator as a tuple (v,p) such that
For the purpose of this lite client specification, we assume that the Tendermint Full Node exposes the following function over Tendermint RPC:
func Commit(height int64) (SignedHeader, error)
// returns signed header: header (with the fields from
// above) with Commit that include signatures of
// validators that signed the header
type SignedHeader struct {
Header Header
Commit Commit
}
If a block h is generated at time bfttime (and this time is stored in the block), then a set of validators that hold more than 2/3 of the voting power in h.Header.NextV is correct until time h.Header.bfttime + TRUSTED_PERIOD.
Formally, [ \sum_{(v,p) \in h.Header.NextV \wedge correct(v,h.Header.bfttime + TRUSTED_PERIOD)} p > 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 this assumption. 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.)
The lite client communicates with a full node and learns new headers. The goal is to locally decide whether to trust a header. Our implementation needs to ensure the following two properties:
Lite Client Completeness: If header h was correctly generated by an instance of Tendermint consensus (and its age is less than the trusting period), then the lite client should eventually set trust(h) to true.
Lite Client Accuracy: If header h was not generated by an instance of Tendermint consensus, then the lite client should never set trust(h) to true.
Remark: If in the course of the computation, the lite client obtains certainty that some headers were forged by adversaries (that is were not generated by an instance of Tendermint consensus), it may submit (a subset of) the headers it has seen as evidence of misbehavior.
Remark: In Completeness we use "eventually", while in practice trust(h) should be set to true before h.Header.bfttime + tp. If not, the block cannot be trusted because it is too old.
Remark: If a header h is marked with trust(h), but it is too old (its bfttime is more than tp ago), then the lite client should set trust(h) to false again.
Assumption: Initially, the lite client has a header inithead that it trusts correctly, that is, inithead was correctly generated by the Tendermint consensus.
To reason about the correctness, we may prove the following invariant.
Verification Condition: Lite Client Invariant. For each lite client l and each header h: if l has set trust(h) = true, then validators that are correct until time h.Header.bfttime + tp have more than two thirds of the voting power in h.Header.NextV.
Formally, [ \sum_{(v,p) \in h.Header.NextV \wedge correct(v,h.Header.bfttime + tp)} p > 2/3 \sum_{(v,p) \in h.Header.NextV} p ]
Remark. To prove the invariant, we will have to prove that the lite client only trusts headers that were correctly generated by Tendermint consensus, then the formula above follows from the Tendermint failure model.
Upon initialization, the lite client is given a header inithead it trusts (by social consensus). It is assumed that inithead satisfies the lite client invariant. (If inithead has been correctly generated by Tendermint consensus, the invariant follows from the Tendermint Failure Model.)
When a lite clients sees a signed new header snh, it has to decide whether to trust the new header. Trust can be obtained by (possibly) the combination of three methods.
Uninterrupted sequence of proof. If a block is appended to the chain, where the last block is trusted (and properly committed by the old validator set in the next block), and the new block contains a new validator set, the new block is trusted if the lite client knows all headers in the prefix. Intuitively, a trusted validator set is assumed to only chose a new validator set that will obey the Tendermint Failure Model.
Trusting period. Based on a trusted block h, and the lite client invariant, which ensures the fault assumption during the trusting period, we can check whether at least one validator, that has been continuously correct from h.Header.bfttime until now, has signed snh. If this is the case, similarly to above, the chosen validator set in snh does not violate the Tendermint Failure Model.
Bisection. If a check according to the trusting period fails, the lite client can try to obtain a header hp whose height lies between h and snh in order to check whether h can be used to get trust for hp, and hp can be used to get trust for snh. If this is the case we can trust snh; if not, we may continue recursively.
We consider the following use case: the lite client wants to verify a header for some given height k. Thus:
This can be used in several settings:
Observation 1. If h.Header.bfttime + tp > now, we trust the old validator set h.Header.NextV.
When we say we trust h.Header.NextV we do not trust that each individual validator in h.Header.NextV is correct, but we only trust the fact that at most 1/3 of them are faulty (more precisely, the faulty ones have at most 1/3 of the total voting power).
The function CanTrust checks whether to trust header h2 based on the trusted header h1. It does so by (potentially) building transitive trust relation between h1 and h2, over some intermediate headers. For example, in case we cannot trust header h2 based on the trusted header h1, the function CanTrust will try to find headers such that we can transition trust from h1 over intermediate headers to h2. 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 h2 given the trust in the header h1 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 h2.Header.height > h1.Header.height. We will quickly discuss the other case in the next section.
We consider the following set-up:
Auxiliary Functions. We will use the function votingpower_in(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 votingpower_in(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 h2 based on header h1.
Time validity of a header is captured by the isWithinTrustedPeriodWithin
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.
// return true if header is within its lite client trusted period; otherwise it returns false
func isWithinTrustedPeriod(h) 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 votingpower_in(signers(h.Commit),h.Header.V) > 2/3 * vp_all
}
// Captures skipping condition. h1 and h2 has already passed basic validation (function `verify`).
// returns nil in case h2 can be trusted based on h1, otherwise returns error.
// ErrHeaderExpired is used to signal that h1 has expired with respect lite client trusted period,
// ErrInvalidAdjacentHeaders that adjacent headers are not consistent and
// ErrTooMuchChange that there is not enough intersection between validator sets to have skipping condition true.
func CheckSupport(h1,h2,trustlevel) error {
assume h1.Header.Height < h2.header.Height and h1.Header.bfttime < h2.Header.bfttime and h2.Header.bfttime < now
if !isWithinTrustedPeriod(h1) return ErrHeaderNotWithinTrustedPeriod(h1)
// Although while executing the rest of CheckSupport function, h1 can expiry 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 h1 can be trusted
// Furthermore, CheckSupport function is not doing expensive operation (neither rpc nor signature verification), so it should execute fast.
// total sum of voting power of validators in h1.NextV
vp_all := totalVotingPower(h1.Header.NextV)
// check for adjacent headers
if (h2.Header.height == h1.Header.height + 1) {
if h1.Header.NextV == h2.Header.V
return nil
return ErrInvalidAdjacentHeaders
}
// check for non-adjacent headers
if votingpower_in(signers(h2.Commit),h1.Header.NextV) > max(1/3,trustlevel) * vp_all return nil
return ErrTooMuchChange
}
Correctness arguments
Towards Lite Client Accuracy:
Towards Lite Client Completeness:
Verification Condition: We may need a Tendermint invariant stating that if h2.Header.height = h1.Header.height + 1 then signers(h2.Commit) \subseteq h1.Header.NextV.
Remark: The variable trustlevel 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 trustlevel 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.
func VerifyHeader(height, trustlevel) error {
if h2, exists := Store.Get(height); exists {
if isWithinTrustedPeriod(h2) return nil
return ErrHeaderNotWithinTrustedPeriod(h2)
}
else {
h2 := Commit(height)
if !verify(h2) return ErrInvalidHeader(h2)
if !isWithinTrustedPeriod(h2) return ErrHeaderNotWithinTrustedPeriod(h2)
}
// get the highest trusted headers lower than h2
h1 = Store.HighestTrustedSmallerThan(height)
if h1 == nil
return ErrNoTrustedHeader
err = CanTrust(h1, h2, trustlevel) // or CanTrustBisection((h1, h2, trustlevel)
if err != nil return err
if isWithinTrustedPeriod(h2) {
Store.add(h2) // we store only trusted headers, as we assume that only trusted headers are influencing end user business decisions.
return nil
}
return ErrHeaderNotTrusted(h2)
}
// return nil in case we can trust header h2 based on header h1; otherwise return error where error captures the nature of the error.
func CanTrust(h1,h2,trustlevel) error {
assume h1.Header.Height < h2.header.Height
err = CheckSupport(h1,h2,trustlevel)
if err == nil {
Store.Add(h2)
return nil
}
if err != ErrTooMuchChange return err
// we cannot verify h2 based on h1, so we try to move trusted header closer to h2 so we can verify h2
th := h1 // th is trusted header
untrustedHeaders := []
while true {
endHeight = h2.Header.height
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,trustlevel)
if (err != nil and err != ErrTooMuchChange) return err
if err == nil {
th = hp
Store.Add(hp)
foundPivot = true
}
untrustedHeaders.add(hp)
endHeight = pivot
}
// try to move trusted header forward
for h in untrustedHeaders {
// we assume here that iteration is done in the order of header heights
err = CheckSupport(th,h,trustlevel)
if (err != nil and err != ErrTooMuchChange) return err
if err == nil {
th = h
Store.Add(h)
untrustedHeaders.Remove(h)
}
}
// at this point we have potentially updated th based on stored headers so we try to verify h2
// based on new trusted header
err = CheckSupport(h1,h2,trustlevel)
if err == nil {
Store.Add(h2)
return nil
}
if err != ErrTooMuchChange return err
}
return nil // this line should never be reached
}
func CanTrustBisection(h1,h2,trustlevel) error {
assume h1.Header.Height < h2.header.Height
err = CheckSupport(h1,h2,trustlevel)
if err == nil {
Store.Add(h2)
return nil
}
if err != ErrTooMuchChange return err
pivot := (h1.Header.height + h2.Header.height) / 2
hp := Commit(pivot)
if !verify(hp) return ErrInvalidHeader(hp)
err = CanTrustBisection(h1,hp,trustlevel)
if err == nil {
Store.Add(hp)
err2 = CanTrustBisection(hp,h2,trustlevel)
if err2 == nil {
Store.Add(h2)
return nil
}
return err2
}
return err
}
Correctness arguments (sketch)
Lite Client Accuracy:
Lite Client Completeness:
This is only ensured if upon Commit(pivot) the lite client is always provided with a correctly generated header.
Stalling
With CanTrustBisection, a faulty full node could stall a lite client by creating a long sequence of headers that are queried one-by-one by the lite client and look OK, before the lite client eventually detects a problem. There are several ways to address this:
Commit
could be issued to a different full nodeIn 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.
func Backwards(h1,h2) error {
assert (h2.Header.height < h1.Header.height)
if !isWithinTrustedPeriod(h1) return ErrHeaderNotTrusted(h1)
old := h1
for i := h1.Header.height - 1; i > h2.Header.height; i-- {
new := Commit(i)
if (hash(new) != old.Header.hash) {
return ErrInvalidAdjacentHeaders
}
old := new
if !isWithinTrustedPeriod(h1) return ErrHeaderNotTrusted(h1)
}
if hash(h2) == old.Header.hash return ErrInvalidAdjacentHeaders
return nil
}