docs: update Light Client Protocol page (#4405)

* docs: update Light Client Protocol page

Closes #4331

* one way to get hash & height

cmd/tendermint/commands/lite.go

@@ -25,13 +25,12 @@ import (
 // LiteCmd represents the base command when called without any subcommands
 var LiteCmd = &cobra.Command{
 	Use:   "lite",
-	Short: "Run lite-client proxy server, verifying tendermint rpc",
-	Long: `This node will run a secure proxy to a tendermint rpc server.
+	Short: "Run a light client proxy server, verifying Tendermint rpc",
+	Long: `Run a light client proxy server, verifying Tendermint rpc.
 
 All calls that can be tracked back to a block header by a proof
-will be verified before passing them back to the caller. Other that
-that it will present the same interface as a full tendermint node,
-just with added trust and running locally.`,
+will be verified before passing them back to the caller. Other than
+that, it will present the same interface as a full Tendermint node.`,
 	RunE:         runProxy,
 	SilenceUsage: true,
 }
@@ -52,27 +51,20 @@ var (
 func init() {
 	LiteCmd.Flags().StringVar(&listenAddr, "laddr", "tcp://localhost:8888",
 		"Serve the proxy on the given address")
-
+	LiteCmd.Flags().StringVar(&chainID, "chain-id", "tendermint", "Specify the Tendermint chain ID")
 	LiteCmd.Flags().StringVar(&primaryAddr, "primary", "tcp://localhost:26657",
 		"Connect to a Tendermint node at this address")
-
 	LiteCmd.Flags().StringVar(&witnessesAddrs, "witnesses", "",
 		"Tendermint nodes to cross-check the primary node, comma-separated")
-
-	LiteCmd.Flags().StringVar(&chainID, "chain-id", "tendermint", "Specify the Tendermint chain ID")
-
 	LiteCmd.Flags().StringVar(&home, "home-dir", ".tendermint-lite", "Specify the home directory")
 	LiteCmd.Flags().IntVar(
 		&maxOpenConnections,
 		"max-open-connections",
 		900,
 		"Maximum number of simultaneous connections (including WebSocket).")
-
 	LiteCmd.Flags().DurationVar(&trustingPeriod, "trusting-period", 168*time.Hour,
 		"Trusting period. Should be significantly less than the unbonding period")
-
 	LiteCmd.Flags().Int64Var(&trustedHeight, "trusted-height", 1, "Trusted header's height")
-
 	LiteCmd.Flags().BytesHexVar(&trustedHash, "trusted-hash", []byte{}, "Trusted header's hash")
 }
 

docs/tendermint-core/light-client-protocol.md

@@ -4,20 +4,19 @@ order: 9
 
 # Light Client Protocol
 
-Light clients are an important part of the complete blockchain system
-for most applications. Tendermint provides unique speed and security
-properties for light client applications.
+Light clients are an important part of the complete blockchain system for most
+applications. Tendermint provides unique speed and security properties for
+light client applications.
 
 See our [lite
-package](https://godoc.org/github.com/tendermint/tendermint/lite).
+package](https://pkg.go.dev/github.com/tendermint/tendermint/lite2?tab=doc).
 
 ## Overview
 
-The objective of the light client protocol is to get a
-commit for a recent block
-hash where the commit includes a
-majority of signatures from the last known validator set. From there,
-all the application state is verifiable with [merkle
+The objective of the light client protocol is to get a commit for a recent
+block hash where the commit includes a majority of signatures from the last
+known validator set. From there, all the application state is verifiable with
+[merkle
 proofs](https://github.com/tendermint/spec/blob/953523c3cb99fdb8c8f7a2d21e3a99094279e9de/spec/blockchain/encoding.md#iavl-tree).
 
 ## Properties
@@ -27,8 +26,38 @@ proofs](https://github.com/tendermint/spec/blob/953523c3cb99fdb8c8f7a2d21e3a9909
 - You get the full speed benefits of Tendermint; transactions
   commit instantly.
 - You can get the most recent version of the application state
-  non-interactively (without committing anything to the blockchain).
-  For example, this means that you can get the most recent value of a
-  name from the name-registry without worrying about fork censorship
-  attacks, without posting a commit and waiting for confirmations.
-  It's fast, secure, and free!
+  non-interactively (without committing anything to the blockchain). For
+  example, this means that you can get the most recent value of a name from the
+  name-registry without worrying about fork censorship attacks, without posting
+  a commit and waiting for confirmations. It's fast, secure, and free!
+
+## Where to obtain trusted height & hash?
+
+https://pkg.go.dev/github.com/tendermint/tendermint/lite2?tab=doc#TrustOptions
+
+One way to obtain semi-trusted hash & height is to query multiple full nodes
+and compare their hashes:
+
+```sh
+$ curl -s https://233.123.0.140:26657:26657/commit | jq "{height: .result.signed_header.header.height, hash: .result.signed_header.commit.block_id.hash}"
+{
+  "height": "273",
+  "hash": "188F4F36CBCD2C91B57509BBF231C777E79B52EE3E0D90D06B1A25EB16E6E23D"
+}
+```
+
+## HTTP proxy
+
+Tendermint comes with a built-in `tendermint lite` command, which can be used
+to run a light client proxy server, verifying Tendermint rpc. All calls that
+can be tracked back to a block header by a proof will be verified before
+passing them back to the caller. Other than that, it will present the same
+interface as a full Tendermint node.
+
+```sh
+$ tendermint lite --chain-id=supernova --primary=tcp://233.123.0.140:26657 \
+  --witnesses=tcp://179.63.29.15:26657,tcp://144.165.223.135:26657 \
+  --trusted-height=10 --trusted-hash=37E9A6DD3FA25E83B22C18835401E8E56088D0D7ABC6FD99FCDC920DD76C1C57
+```
+
+For additional options, run `tendermint lite --help`.

lite2/doc.go

@@ -76,24 +76,29 @@ Example usage:
 				Hash:   header.Hash(),
 			},
 			httpp.New(chainID, "tcp://localhost:26657"),
+			[]provider.Provider{httpp.New(chainID, "tcp://witness1:26657")},
 			dbs.New(db, chainID),
 		)
 
-		err = c.VerifyHeaderAtHeight(101, time.Now())
+		err = c.Start()
 		if err != nil {
-			fmt.Println("retry?")
+			// return err
+			t.Fatal(err)
 		}
+		defer c.Stop()
 
 		h, err := c.TrustedHeader(101)
 		if err != nil {
-			fmt.Println("retry?")
+			// handle error
 		}
 		fmt.Println("got header", h)
 
+Check out other examples in example_test.go
+
 ## 2. Pure functions to verify a new header (see verifier.go)
 
 Verify function verifies a new header against some trusted header. See
-https://github.com/tendermint/spec/blob/master/spec/consensus/light-client.md
+https://github.com/tendermint/spec/blob/master/spec/consensus/light-client/verification.md
 for details.
 
 ## 3. Secure RPC proxy
@@ -105,7 +110,7 @@ as a wrapper, which verifies all the headers, using a light client connected to
 some other node.
 
 See
-https://github.com/tendermint/tendermint/blob/master/cmd/tendermint/commands/lite.go
+https://docs.tendermint.com/master/tendermint-core/light-client-protocol.html
 for usage example.
 */
 package lite