You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
127 lines
4.8 KiB
127 lines
4.8 KiB
/*
|
|
package light 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 light 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.
|
|
|
|
# Common structures
|
|
|
|
* SignedHeader
|
|
|
|
SignedHeader is a block header along with a commit -- enough validator
|
|
precommit-vote signatures to prove its validity (> 2/3 of the voting power)
|
|
given the validator set responsible for signing that header.
|
|
|
|
The hash of the next validator set is included and signed in the SignedHeader.
|
|
This lets the light client keep track of arbitrary changes to the validator set,
|
|
as every change to the validator set must be approved by inclusion in the
|
|
header and signed in the commit.
|
|
|
|
In the worst case, with every block changing the validators around completely,
|
|
a light client can sync up with every block header to verify each validator set
|
|
change on the chain. In practice, most applications will not have frequent
|
|
drastic updates to the validator set, so the logic defined in this package for
|
|
light client syncing is optimized to use intelligent bisection.
|
|
|
|
# What this package provides
|
|
|
|
This package provides three major things:
|
|
|
|
1. Client implementation (see client.go)
|
|
2. Pure functions to verify a new header (see verifier.go)
|
|
3. Secure RPC proxy
|
|
|
|
## 1. Client implementation (see client.go)
|
|
|
|
Example usage:
|
|
|
|
db, err := dbm.NewGoLevelDB("light-client-db", dbDir)
|
|
if err != nil {
|
|
// handle error
|
|
}
|
|
|
|
c, err := NewHTTPClient(
|
|
chainID,
|
|
TrustOptions{
|
|
Period: 504 * time.Hour, // 21 days
|
|
Height: 100,
|
|
Hash: header.Hash(),
|
|
},
|
|
"http://localhost:26657",
|
|
[]string{"http://witness1:26657"},
|
|
dbs.New(db, ""),
|
|
)
|
|
if err != nil {
|
|
// handle error
|
|
}
|
|
|
|
h, err := c.TrustedHeader(100)
|
|
if err != nil {
|
|
// handle error
|
|
}
|
|
fmt.Println("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/verification.md
|
|
for details.
|
|
|
|
There are two methods of verification: sequential and bisection
|
|
|
|
Sequential uses the headers hashes and the validator sets to verify each adjacent header until
|
|
it reaches the target header.
|
|
|
|
Bisection finds the middle header between a trusted and new header, reiterating the action until it
|
|
verifies a header. A cache of headers requested by the primary is kept such that when a
|
|
verification is made, and the light client tries again to verify the new header in the middle,
|
|
the light client does not need to ask for all the same headers again.
|
|
|
|
refer to docs/imgs/light_client_bisection_alg.png
|
|
|
|
## 3. Secure RPC proxy
|
|
|
|
Tendermint RPC exposes a lot of info, but a malicious node could return any
|
|
data it wants to queries, or even to block headers, even making up fake
|
|
signatures from non-existent validators to justify it. Secure RPC proxy serves
|
|
as a wrapper, which verifies all the headers, using a light client connected to
|
|
some other node.
|
|
|
|
See
|
|
https://docs.tendermint.com/master/tendermint-core/light-client-protocol.html
|
|
for usage example.
|
|
Or see
|
|
https://github.com/tendermint/spec/tree/master/spec/consensus/light-client
|
|
for the full spec
|
|
*/
|
|
package light
|