github.com/okex/exchain@v1.8.0/libs/tendermint/lite/doc.go (about)

     1  /*
     2  Package lite is deprecated and will be removed in v0.34!
     3  
     4  Package lite allows you to securely validate headers without a full node.
     5  
     6  This library pulls together all the crypto and algorithms, so given a
     7  relatively recent (< unbonding period) known validator set, one can get
     8  indisputable proof that data is in the chain (current state) or detect if the
     9  node is lying to the client.
    10  
    11  Tendermint RPC exposes a lot of info, but a malicious node could return any
    12  data it wants to queries, or even to block headers, even making up fake
    13  signatures from non-existent validators to justify it. This is a lot of logic
    14  to get right, to be contained in a small, easy to use library, that does this
    15  for you, so you can just build nice applications.
    16  
    17  We design for clients who have no strong trust relationship with any Tendermint
    18  node, just the blockchain and validator set as a whole.
    19  
    20  SignedHeader
    21  
    22  SignedHeader is a block header along with a commit -- enough validator
    23  precommit-vote signatures to prove its validity (> 2/3 of the voting power)
    24  given the validator set responsible for signing that header. A FullCommit is a
    25  SignedHeader along with the current and next validator sets.
    26  
    27  The hash of the next validator set is included and signed in the SignedHeader.
    28  This lets the lite client keep track of arbitrary changes to the validator set,
    29  as every change to the validator set must be approved by inclusion in the
    30  header and signed in the commit.
    31  
    32  In the worst case, with every block changing the validators around completely,
    33  a lite client can sync up with every block header to verify each validator set
    34  change on the chain. In practice, most applications will not have frequent
    35  drastic updates to the validator set, so the logic defined in this package for
    36  lite client syncing is optimized to use intelligent bisection and
    37  block-skipping for efficient sourcing and verification of these data structures
    38  and updates to the validator set (see the DynamicVerifier for more
    39  information).
    40  
    41  The FullCommit is also declared in this package as a convenience structure,
    42  which includes the SignedHeader along with the full current and next
    43  ValidatorSets.
    44  
    45  Verifier
    46  
    47  A Verifier validates a new SignedHeader given the currently known state. There
    48  are two different types of Verifiers provided.
    49  
    50  BaseVerifier - given a validator set and a height, this Verifier verifies
    51  that > 2/3 of the voting power of the given validator set had signed the
    52  SignedHeader, and that the SignedHeader was to be signed by the exact given
    53  validator set, and that the height of the commit is at least height (or
    54  greater).
    55  
    56  DynamicVerifier - this Verifier implements an auto-update and persistence
    57  strategy to verify any SignedHeader of the blockchain.
    58  
    59  Provider and PersistentProvider
    60  
    61  A Provider allows us to store and retrieve the FullCommits.
    62  
    63      type Provider interface {
    64          // LatestFullCommit returns the latest commit with
    65          // minHeight <= height <= maxHeight.
    66          // If maxHeight is zero, returns the latest where
    67          // minHeight <= height.
    68          LatestFullCommit(chainID string, minHeight, maxHeight int64) (FullCommit, error)
    69      }
    70  
    71  * client.NewHTTPProvider - query Tendermint rpc.
    72  
    73  A PersistentProvider is a Provider that also allows for saving state.  This is
    74  used by the DynamicVerifier for persistence.
    75  
    76      type PersistentProvider interface {
    77          Provider
    78  
    79          // SaveFullCommit saves a FullCommit (without verification).
    80          SaveFullCommit(fc FullCommit) error
    81      }
    82  
    83  * DBProvider - persistence provider for use with any libs/DB.
    84  
    85  * MultiProvider - combine multiple providers.
    86  
    87  The suggested use for local light clients is client.NewHTTPProvider(...) for
    88  getting new data (Source), and NewMultiProvider(NewDBProvider("label",
    89  dbm.NewMemDB()), NewDBProvider("label", db.NewFileDB(...))) to store confirmed
    90  full commits (Trusted)
    91  
    92  
    93  How We Track Validators
    94  
    95  Unless you want to blindly trust the node you talk with, you need to trace
    96  every response back to a hash in a block header and validate the commit
    97  signatures of that block header match the proper validator set.  If there is a
    98  static validator set, you store it locally upon initialization of the client,
    99  and check against that every time.
   100  
   101  If the validator set for the blockchain is dynamic, verifying block commits is
   102  a bit more involved -- if there is a block at height H with a known (trusted)
   103  validator set V, and another block at height H' (H' > H) with validator set V'
   104  != V, then we want a way to safely update it.
   105  
   106  First, we get the new (unconfirmed) validator set V' and verify that H' is
   107  internally consistent and properly signed by this V'. Assuming it is a valid
   108  block, we check that at least 2/3 of the validators in V also signed it,
   109  meaning it would also be valid under our old assumptions.  Then, we accept H'
   110  and V' as valid and trusted and use that to validate for heights X > H' until a
   111  more recent and updated validator set is found.
   112  
   113  If we cannot update directly from H -> H' because there was too much change to
   114  the validator set, then we can look for some Hm (H < Hm < H') with a validator
   115  set Vm.  Then we try to update H -> Hm and then Hm -> H' in two steps.  If one
   116  of these steps doesn't work, then we continue bisecting, until we eventually
   117  have to externally validate the validator set changes at every block.
   118  
   119  Since we never trust any server in this protocol, only the signatures
   120  themselves, it doesn't matter if the seed comes from a (possibly malicious)
   121  node or a (possibly malicious) user.  We can accept it or reject it based only
   122  on our trusted validator set and cryptographic proofs. This makes it extremely
   123  important to verify that you have the proper validator set when initializing
   124  the client, as that is the root of all trust.
   125  
   126  The software currently assumes that the unbonding period is infinite in
   127  duration.  If the DynamicVerifier hasn't been updated in a while, you should
   128  manually verify the block headers using other sources.
   129  
   130  TODO: Update the software to handle cases around the unbonding period.
   131  
   132  */
   133  package lite