lite

Documentation

Overview

Package lite allows you to securely validate headers without a full node.

This library pulls together all the crypto and algorithms, so given a relatively recent (< unbonding period) known validator set, one can get indisputable proof that data is in the chain (current state) or detect if the node is lying to the client.

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. This is a lot of logic to get right, to be contained in a small, easy to use library, that does this for you, so you can just build nice UI.

We design for clients who have no strong trust relationship with any tendermint node, just the validator set as a whole. Beyond building nice mobile or desktop applications, the cosmos hub is another important example of a client, that needs undeniable proof without syncing the full chain, in order to efficiently implement IBC.

Commits

There are two main data structures that we pass around - Commit and FullCommit. Both of them mirror what information is exposed in tendermint rpc.

Commit is a block header along with enough validator signatures to prove its validity (> 2/3 of the voting power). A FullCommit is a Commit along with the full validator set. When the validator set doesn't change, the Commit is enough, but since the block header only has a hash, we need the FullCommit to follow any changes to the validator set.

Certifiers

A Certifier validates a new Commit given the currently known state. There are three different types of Certifiers exposed, each one building on the last one, with additional complexity.

Static - given the validator set upon initialization. Verifies all signatures against that set and if the validator set changes, it will reject all headers.

Dynamic - This wraps Static and has the same Certify method. However, it adds an Update method, which can be called with a FullCommit when the validator set changes. If it can prove this is a valid transition, it will update the validator set.

Inquiring - this wraps Dynamic and implements an auto-update strategy on top of the Dynamic update. If a call to Certify fails as the validator set has changed, then it attempts to find a FullCommit and Update to that header. To get these FullCommits, it makes use of a Provider.

Providers

A Provider allows us to store and retrieve the FullCommits, to provide memory to the Inquiring Certifier.

NewMemStoreProvider - in-memory cache.

files.NewProvider - disk backed storage.

client.NewHTTPProvider - query tendermint rpc.

NewCacheProvider - combine multiple providers.

The suggested use for local light clients is client.NewHTTPProvider for getting new data (Source), and NewCacheProvider(NewMemStoreProvider(), files.NewProvider()) to store confirmed headers (Trusted)

How We Track Validators

Unless you want to blindly trust the node you talk with, you need to trace every response back to a hash in a block header and validate the commit signatures of that block header match the proper validator set. If there is a contant validator set, you store it locally upon initialization of the client, and check against that every time.

Once there is a dynamic validator set, the issue of verifying a block becomes a bit more tricky. There is background information in a github issue (https://github.com/tendermint/tendermint/issues/377).

In short, if there is a block at height H with a known (trusted) validator set V, and another block at height H' (H' > H) with validator set V' != V, then we want a way to safely update it.

First, get the new (unconfirmed) validator set V' and verify H' is internally consistent and properly signed by this V'. Assuming it is a valid block, we check that at least 2/3 of the validators in V also signed it, meaning it would also be valid under our old assumptions. That should be enough, but we can also check that the V counts for at least 2/3 of the total votes in H' for extra safety (we can have a discussion if this is strictly required). If we can verify all this, then we can accept H' and V' as valid and use that to validate all blocks X > H'.

If we cannot update directly from H -> H' because there was too much change to the validator set, then we can look for some Hm (H < Hm < H') with a validator set Vm. Then we try to update H -> Hm and Hm -> H' in two separate steps. If one of these steps doesn't work, then we continue bisecting, until we eventually have to externally validate the valdiator set changes at every block.

Since we never trust any server in this protocol, only the signatures themselves, it doesn't matter if the seed comes from a (possibly malicious) node or a (possibly malicious) user. We can accept it or reject it based only on our trusted validator set and cryptographic proofs. This makes it extremely important to verify that you have the proper validator set when initializing the client, as that is the root of all trust.

Or course, this assumes that the known block is within the unbonding period to avoid the "nothing at stake" problem. If you haven't seen the state in a few months, you will need to manually verify the new validator set hash using off-chain means (the same as getting the initial hash).

Index

• type Certifier
• type Commit
  • func (c Commit) Height() int64
  • func (c Commit) ValidateBasic(chainID string) error
  • func (c Commit) ValidatorsHash() []byte
• type DynamicCertifier
  • func NewDynamicCertifier(chainID string, vals *types.ValidatorSet, height int64) *DynamicCertifier
  • func (dc *DynamicCertifier) Certify(check Commit) error
  • func (dc *DynamicCertifier) ChainID() string
  • func (dc *DynamicCertifier) Hash() []byte
  • func (dc *DynamicCertifier) LastHeight() int64
  • func (dc *DynamicCertifier) Update(fc FullCommit) error
  • func (dc *DynamicCertifier) Validators() *types.ValidatorSet
• type FullCommit
  • func NewFullCommit(commit Commit, vals *types.ValidatorSet) FullCommit
• type InquiringCertifier
  • func NewInquiringCertifier(chainID string, fc FullCommit, trusted Provider, source Provider) (*InquiringCertifier, error)
  • func (ic *InquiringCertifier) Certify(commit Commit) error
  • func (ic *InquiringCertifier) ChainID() string
  • func (ic *InquiringCertifier) LastHeight() int64
  • func (ic *InquiringCertifier) Update(fc FullCommit) error
  • func (ic *InquiringCertifier) Validators() *types.ValidatorSet
• type Provider
  • func NewCacheProvider(providers ...Provider) Provider
  • func NewMemStoreProvider() Provider
• type StaticCertifier
  • func NewStaticCertifier(chainID string, vals *types.ValidatorSet) *StaticCertifier
  • func (sc *StaticCertifier) Certify(commit Commit) error
  • func (sc *StaticCertifier) ChainID() string
  • func (sc *StaticCertifier) Hash() []byte
  • func (sc *StaticCertifier) Validators() *types.ValidatorSet
• type ValKeys
  • func GenSecpValKeys(n int) ValKeys
  • func GenValKeys(n int) ValKeys
  • func (v ValKeys) Change(i int) ValKeys
  • func (v ValKeys) Extend(n int) ValKeys
  • func (v ValKeys) ExtendSecp(n int) ValKeys
  • func (v ValKeys) GenCommit(chainID string, height int64, txs types.Txs, vals *types.ValidatorSet, ...) Commit
  • func (v ValKeys) GenFullCommit(chainID string, height int64, txs types.Txs, vals *types.ValidatorSet, ...) FullCommit
  • func (v ValKeys) ToValidators(init, inc int64) *types.ValidatorSet

Types

type Certifier

type Certifier interface {
	Certify(check Commit) error
	ChainID() string
}

Certifier checks the votes to make sure the block really is signed properly. Certifier must know the current set of validitors by some other means.

type Commit

type Commit types.SignedHeader

Commit is basically the rpc /commit response, but extended

This is the basepoint for proving anything on the blockchain. It contains a signed header. If the signatures are valid and > 2/3 of the known set, we can store this checkpoint and use it to prove any number of aspects of the system: such as txs, abci state, validator sets, etc...

func (Commit) Height

func (c Commit) Height() int64

Height returns the height of the header.

func (Commit) ValidateBasic

func (c Commit) ValidateBasic(chainID string) error

ValidateBasic does basic consistency checks and makes sure the headers and commits are all consistent and refer to our chain.

Make sure to use a Verifier to validate the signatures actually provide a significantly strong proof for this header's validity.

func (Commit) ValidatorsHash

func (c Commit) ValidatorsHash() []byte

ValidatorsHash returns the hash of the validator set.

type DynamicCertifier

type DynamicCertifier struct {
	// contains filtered or unexported fields
}

DynamicCertifier uses a StaticCertifier for Certify, but adds an Update method to allow for a change of validators.

You can pass in a FullCommit with another validator set, and if this is a provably secure transition (< 1/3 change, sufficient signatures), then it will update the validator set for the next Certify call. For security, it will only follow validator set changes going forward.

func NewDynamicCertifier

func NewDynamicCertifier(chainID string, vals *types.ValidatorSet, height int64) *DynamicCertifier

NewDynamic returns a new dynamic certifier.

func (*DynamicCertifier) Certify

func (dc *DynamicCertifier) Certify(check Commit) error

Certify will verify whether the commit is valid and will update the height if it is or return an error if it is not. Implements Certifier.

func (*DynamicCertifier) ChainID

func (dc *DynamicCertifier) ChainID() string

ChainID returns the chain id of this certifier. Implements Certifier.

func (*DynamicCertifier) Hash

func (dc *DynamicCertifier) Hash() []byte

Hash returns the hash of this certifier.

func (*DynamicCertifier) LastHeight

func (dc *DynamicCertifier) LastHeight() int64

LastHeight returns the last height of this certifier.

func (*DynamicCertifier) Update

func (dc *DynamicCertifier) Update(fc FullCommit) error

Update will verify if this is a valid change and update the certifying validator set if safe to do so.

Returns an error if update is impossible (invalid proof or IsTooMuchChangeErr)

func (*DynamicCertifier) Validators

func (dc *DynamicCertifier) Validators() *types.ValidatorSet

Validators returns the validators of this certifier.

type FullCommit

type FullCommit struct {
	Commit     `json:"commit"`
	Validators *types.ValidatorSet `json:"validator_set"`
}

FullCommit is a commit and the actual validator set, the base info you need to update to a given point, assuming knowledge of some previous validator set

func NewFullCommit

func NewFullCommit(commit Commit, vals *types.ValidatorSet) FullCommit

NewFullCommit returns a new FullCommit.

type InquiringCertifier

type InquiringCertifier struct {

	// This is a source of new info, like a node rpc, or other import method
	Source Provider
	// contains filtered or unexported fields
}

InquiringCertifier wraps a dynamic certifier and implements an auto-update strategy. If a call to Certify fails due to a change it validator set, InquiringCertifier will try and find a previous FullCommit which it can use to safely update the validator set. It uses a source provider to obtain the needed FullCommits. It stores properly validated data on the local system.

func NewInquiringCertifier

func NewInquiringCertifier(chainID string, fc FullCommit, trusted Provider,
	source Provider) (*InquiringCertifier, error)

NewInquiringCertifier returns a new Inquiring object. It uses the trusted provider to store validated data and the source provider to obtain missing FullCommits.

Example: The trusted provider should a CacheProvider, MemProvider or files.Provider. The source provider should be a client.HTTPProvider.

func (*InquiringCertifier) Certify

func (ic *InquiringCertifier) Certify(commit Commit) error

Certify makes sure this is checkpoint is valid.

If the validators have changed since the last know time, it looks for a path to prove the new validators.

On success, it will store the checkpoint in the store for later viewing Implements Certifier.

func (*InquiringCertifier) ChainID

func (ic *InquiringCertifier) ChainID() string

ChainID returns the chain id. Implements Certifier.

func (*InquiringCertifier) LastHeight

func (ic *InquiringCertifier) LastHeight() int64

LastHeight returns the last height.

func (*InquiringCertifier) Update

func (ic *InquiringCertifier) Update(fc FullCommit) error

Update will verify if this is a valid change and update the certifying validator set if safe to do so.

func (*InquiringCertifier) Validators

func (ic *InquiringCertifier) Validators() *types.ValidatorSet

Validators returns the validator set.

type Provider

type Provider interface {
	// StoreCommit saves a FullCommit after we have verified it,
	// so we can query for it later. Important for updating our
	// store of trusted commits.
	StoreCommit(fc FullCommit) error
	// GetByHeight returns the closest commit with height <= h.
	GetByHeight(h int64) (FullCommit, error)
	// GetByHash returns a commit exactly matching this validator hash.
	GetByHash(hash []byte) (FullCommit, error)
	// LatestCommit returns the newest commit stored.
	LatestCommit() (FullCommit, error)
}

Provider is used to get more validators by other means.

Examples: MemProvider, files.Provider, client.Provider, CacheProvider....

func NewCacheProvider

func NewCacheProvider(providers ...Provider) Provider

NewCacheProvider returns a new provider which wraps multiple other providers.

func NewMemStoreProvider

func NewMemStoreProvider() Provider

NewMemStoreProvider returns a new in-memory provider.

type StaticCertifier

type StaticCertifier struct {
	// contains filtered or unexported fields
}

StaticCertifier assumes a static set of validators, set on initilization and checks against them. The signatures on every header is checked for > 2/3 votes against the known validator set upon Certify

Good for testing or really simple chains. Building block to support real-world functionality.

func NewStaticCertifier

func NewStaticCertifier(chainID string, vals *types.ValidatorSet) *StaticCertifier

NewStaticCertifier returns a new certifier with a static validator set.

func (*StaticCertifier) Certify

func (sc *StaticCertifier) Certify(commit Commit) error

Certify makes sure that the commit is valid. Implements Certifier.

func (*StaticCertifier) ChainID

func (sc *StaticCertifier) ChainID() string

ChainID returns the chain id. Implements Certifier.

func (*StaticCertifier) Hash

func (sc *StaticCertifier) Hash() []byte

Hash returns the hash of the validator set.

func (*StaticCertifier) Validators

func (sc *StaticCertifier) Validators() *types.ValidatorSet

Validators returns the validator set.

type ValKeys

type ValKeys []crypto.PrivKey

ValKeys is a helper for testing.

It lets us simulate signing with many keys, either ed25519 or secp256k1. The main use case is to create a set, and call GenCommit to get properly signed header for testing.

You can set different weights of validators each time you call ToValidators, and can optionally extend the validator set later with Extend or ExtendSecp

func GenSecpValKeys

func GenSecpValKeys(n int) ValKeys

GenSecpValKeys produces an array of secp256k1 private keys to generate commits.

func GenValKeys

func GenValKeys(n int) ValKeys

GenValKeys produces an array of private keys to generate commits.

func (ValKeys) Change

func (v ValKeys) Change(i int) ValKeys

Change replaces the key at index i.

func (ValKeys) Extend

func (v ValKeys) Extend(n int) ValKeys

Extend adds n more keys (to remove, just take a slice).

func (ValKeys) ExtendSecp

func (v ValKeys) ExtendSecp(n int) ValKeys

ExtendSecp adds n more secp256k1 keys (to remove, just take a slice).

func (ValKeys) GenCommit

func (v ValKeys) GenCommit(chainID string, height int64, txs types.Txs,
	vals *types.ValidatorSet, appHash, consHash, resHash []byte, first, last int) Commit

GenCommit calls genHeader and signHeader and combines them into a Commit.

func (ValKeys) GenFullCommit

func (v ValKeys) GenFullCommit(chainID string, height int64, txs types.Txs,
	vals *types.ValidatorSet, appHash, consHash, resHash []byte, first, last int) FullCommit

GenFullCommit calls genHeader and signHeader and combines them into a Commit.

func (ValKeys) ToValidators

func (v ValKeys) ToValidators(init, inc int64) *types.ValidatorSet

ToValidators produces a list of validators from the set of keys The first key has weight `init` and it increases by `inc` every step so we can have all the same weight, or a simple linear distribution (should be enough for testing).