github.com/vipernet-xyz/tm@v0.34.24/light/doc.go (about)

     1  /*
     2  package light provides a light client implementation.
     3  
     4  The concept of light clients was introduced in the Bitcoin white paper. It
     5  describes a watcher of distributed consensus process that only validates the
     6  consensus algorithm and not the state machine transactions within.
     7  
     8  Tendermint light clients allow bandwidth & compute-constrained devices, such as
     9  smartphones, low-power embedded chips, or other blockchains to efficiently
    10  verify the consensus of a Tendermint blockchain. This forms the basis of safe
    11  and efficient state synchronization for new network nodes and inter-blockchain
    12  communication (where a light client of one Tendermint instance runs in another
    13  chain's state machine).
    14  
    15  In a network that is expected to reliably punish validators for misbehavior by
    16  slashing bonded stake and where the validator set changes infrequently, clients
    17  can take advantage of this assumption to safely synchronize a light client
    18  without downloading the intervening headers.
    19  
    20  Light clients (and full nodes) operating in the Proof Of Stake context need a
    21  trusted block height from a trusted source that is no older than 1 unbonding
    22  window plus a configurable evidence submission synchrony bound. This is called
    23  weak subjectivity.
    24  
    25  Weak subjectivity is required in Proof of Stake blockchains because it is
    26  costless for an attacker to buy up voting keys that are no longer bonded and
    27  fork the network at some point in its prior history. See Vitalik's post at
    28  [Proof of Stake: How I Learned to Love Weak
    29  Subjectivity](https://blog.ethereum.org/2014/11/25/proof-stake-learned-love-weak-subjectivity/).
    30  
    31  NOTE: Tendermint provides a somewhat different (stronger) light client model
    32  than Bitcoin under eclipse, since the eclipsing node(s) can only fool the light
    33  client if they have two-thirds of the private keys from the last root-of-trust.
    34  
    35  # Common structures
    36  
    37  * SignedHeader
    38  
    39  SignedHeader is a block header along with a commit -- enough validator
    40  precommit-vote signatures to prove its validity (> 2/3 of the voting power)
    41  given the validator set responsible for signing that header.
    42  
    43  The hash of the next validator set is included and signed in the SignedHeader.
    44  This lets the light client keep track of arbitrary changes to the validator set,
    45  as every change to the validator set must be approved by inclusion in the
    46  header and signed in the commit.
    47  
    48  In the worst case, with every block changing the validators around completely,
    49  a light client can sync up with every block header to verify each validator set
    50  change on the chain. In practice, most applications will not have frequent
    51  drastic updates to the validator set, so the logic defined in this package for
    52  light client syncing is optimized to use intelligent bisection.
    53  
    54  # What this package provides
    55  
    56  This package provides three major things:
    57  
    58  1. Client implementation (see client.go)
    59  2. Pure functions to verify a new header (see verifier.go)
    60  3. Secure RPC proxy
    61  
    62  ## 1. Client implementation (see client.go)
    63  
    64  Example usage:
    65  
    66  	db, err := dbm.NewGoLevelDB("light-client-db", dbDir)
    67  	if err != nil {
    68  		// handle error
    69  	}
    70  
    71  	c, err := NewHTTPClient(
    72  		chainID,
    73  		TrustOptions{
    74  			Period: 504 * time.Hour, // 21 days
    75  			Height: 100,
    76  			Hash:   header.Hash(),
    77  		},
    78  		"http://localhost:26657",
    79  		[]string{"http://witness1:26657"},
    80  		dbs.New(db, ""),
    81  	)
    82  	if err != nil {
    83  		// handle error
    84  	}
    85  
    86  	h, err := c.TrustedHeader(100)
    87  	if err != nil {
    88  		// handle error
    89  	}
    90  	fmt.Println("header", h)
    91  
    92  Check out other examples in example_test.go
    93  
    94  ## 2. Pure functions to verify a new header (see verifier.go)
    95  
    96  Verify function verifies a new header against some trusted header. See
    97  https://github.com/vipernet-xyz/tm/blob/v0.34.x/spec/consensus/light-client/verification.md
    98  for details.
    99  
   100  There are two methods of verification: sequential and bisection
   101  
   102  Sequential uses the headers hashes and the validator sets to verify each adjacent header until
   103  it reaches the target header.
   104  
   105  Bisection finds the middle header between a trusted and new header, reiterating the action until it
   106  verifies a header. A cache of headers requested by the primary is kept such that when a
   107  verification is made, and the light client tries again to verify the new header in the middle,
   108  the light client does not need to ask for all the same headers again.
   109  
   110  refer to docs/imgs/light_client_bisection_alg.png
   111  
   112  ## 3. Secure RPC proxy
   113  
   114  Tendermint RPC exposes a lot of info, but a malicious node could return any
   115  data it wants to queries, or even to block headers, even making up fake
   116  signatures from non-existent validators to justify it. Secure RPC proxy serves
   117  as a wrapper, which verifies all the headers, using a light client connected to
   118  some other node.
   119  
   120  See
   121  https://docs.tendermint.com/v0.34/tendermint-core/light-client-protocol.html
   122  for usage example.
   123  Or see
   124  https://github.com/vipernet-xyz/tm/tree/v0.34.x/spec/consensus/light-client
   125  for the full spec
   126  */
   127  package light