add more docs from ADR-44

lite/commit.go

@@ -10,7 +10,7 @@ import (
 
 // FullCommit contains a SignedHeader (the block's header and a commit that
 // signs it), the validator set which signed the commit, and the next validator
-// set. 
+// set.
 // The next validator set (which is proven from the block header) allows us to
 // revert to block-by-block updating of lite Verifier's latest validator set,
 // even in the face of arbitrarily large power changes.

lite/doc.go

@@ -1,5 +1,38 @@
 /*
-Package lite allows you to securely validate headers without a full node.
+Package lite provides a light client implementation.
+
+The concept of light clients was introduced in the Bitcoin white paper. It
+describes a watcher of distributed consensus process that only validates the
+consensus algorithm and not the state machine transactions within.
+
+Tendermint light clients allow bandwidth & compute-constrained devices, such as
+smartphones, low-power embedded chips, or other blockchains to efficiently
+verify the consensus of a Tendermint blockchain. This forms the basis of safe
+and efficient state synchronization for new network nodes and inter-blockchain
+communication (where a light client of one Tendermint instance runs in another
+chain's state machine).
+
+In a network that is expected to reliably punish validators for misbehavior by
+slashing bonded stake and where the validator set changes infrequently, clients
+can take advantage of this assumption to safely synchronize a lite client
+without downloading the intervening headers.
+
+Light clients (and full nodes) operating in the Proof Of Stake context need a
+trusted block height from a trusted source that is no older than 1 unbonding
+window plus a configurable evidence submission synchrony bound. This is called
+weak subjectivity.
+
+Weak subjectivity is required in Proof of Stake blockchains because it is
+costless for an attacker to buy up voting keys that are no longer bonded and
+fork the network at some point in its prior history. See Vitalik's post at
+[Proof of Stake: How I Learned to Love Weak
+Subjectivity](https://blog.ethereum.org/2014/11/25/proof-stake-learned-love-weak-subjectivity/).
+
+NOTE: Tendermint provides a somewhat different (stronger) light client model
+than Bitcoin under eclipse, since the eclipsing node(s) can only fool the light
+client if they have two-thirds of the private keys from the last root-of-trust.
+
+===
 
 This library pulls together all the crypto and algorithms, so given a
 relatively recent (< unbonding period) known validator set, one can get

lite/verifier.go

@@ -10,7 +10,7 @@ import (
 	"github.com/tendermint/tendermint/types"
 )
 
-// verifier lets us check the validity of SignedHeaders at height or later,
+// verifier lets us check the validity of SignedHeaders at the given height or later,
 // requiring sufficient votes (> 2/3) from the given valset. To verify blocks
 // produced by a blockchain with mutable validator sets, use the
 // DynamicVerifier.

lite/verifying/provider.go

@@ -1,6 +1,3 @@
-/*
-Package verifying
-*/
 package verifying
 
 import (
@@ -29,10 +26,20 @@ const (
 	sizeOfPendingMap = 1024
 )
 
-// TrustOptions are the trust parameters.
+// TrustOptions are the trust parameters needed for when a new light client
+// connects to the network or when a light client that has been offline for
+// longer than the unbonding period connects to the network.
+//
+// The expectation is the user will get this information from a trusted source
+// like a validator, a friend, or a secure website. A more user friendly
+// solution with trust tradeoffs is that we establish an https based protocol
+// with a default end point that populates this information. Also an on-chain
+// registry of roots-of-trust (e.g. on the Cosmos Hub) seems likely in the
+// future.
 type TrustOptions struct {
 	// Required: only trust commits up to this old.
-	// Should be equal to the unbonding period.
+	// Should be equal to the unbonding period minus a configurable evidence
+	// submission synchrony bound.
 	TrustPeriod time.Duration `json:"trust-period"`
 
 	// Option 1: TrustHeight and TrustHash can both be provided