From 774aff5f7d60725062aed57cdf5733a8ab9b5b11 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Fri, 14 Feb 2020 11:22:17 +0100 Subject: [PATCH] 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 | 18 ++---- docs/tendermint-core/light-client-protocol.md | 57 ++++++++++++++----- lite2/doc.go | 15 +++-- 3 files changed, 58 insertions(+), 32 deletions(-) diff --git a/cmd/tendermint/commands/lite.go b/cmd/tendermint/commands/lite.go index f27c34cf1..8477b46ed 100644 --- a/cmd/tendermint/commands/lite.go +++ b/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") } diff --git a/docs/tendermint-core/light-client-protocol.md b/docs/tendermint-core/light-client-protocol.md index 1296fa471..4537412c1 100644 --- a/docs/tendermint-core/light-client-protocol.md +++ b/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`. diff --git a/lite2/doc.go b/lite2/doc.go index 920032f36..aa280e64f 100644 --- a/lite2/doc.go +++ b/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