commitment

README

State Commitment (SC)

The commitment package contains the state commitment (SC) implementation. Specifically, it contains an IAVL v1 implementation of SC and the necessary types and abstractions to support other SC backends, as well as supporting general integration into store/v2, specifically the RootStore type.

A foremost design goal is that SC backends should be easily swappable, i.e. not necessarily IAVL. To this end, the scope of SC has been reduced, it must only:

• Provide a stateful root app hash for height h resulting from applying a batch of key-value set/deletes to height h-1.
• Fulfill (though not necessarily provide) historical proofs for all heights < h.
• Provide an API for snapshot create/restore to fulfill state sync requests.

Notably, SC is not required to provide key iteration or value retrieval for either queries or state machine execution, this now being the responsibility of state storage.

An SC implementation may choose not to provide historical proofs past height h - n (n can be 0) due to the time and space constraints, but since store/v2 defines an API for historical proofs there should be at least one configuration of a given SC backend which supports this.

Benchmarks

See this section for specifics on SC benchmarks on various implementations.

Pruning

State Sync

State commitment (SC) does not have a direct notion of state sync. Rather, snapshots.Manager is responsible for creating and restoring snapshots of the entire state. The snapshots.Manager has a CommitSnapshotter field which is fulfilled by the CommitStore type, specifically it implements the Snapshot and Restore methods.

Usage

Similar to the storage package, the commitment package is designed to be used in a broader store implementation, i.e. it fulfills the role of the SC backend. Specifically, it provides a CommitStore type which accepts a corestore.KVStore and a mapping from store key, a string meant to represent a single module, to a Tree, which reflects the commitment structure.

Documentation

Index

• Variables
• type CommitStore
  • func NewCommitStore(trees map[string]Tree, db corestore.KVStoreWithBatch, logger log.Logger) (*CommitStore, error)
  • func (c *CommitStore) Close() (ferr error)
  • func (c *CommitStore) Commit(version uint64) (*proof.CommitInfo, error)
  • func (c *CommitStore) Get(storeKey []byte, version uint64, key []byte) ([]byte, error)
  • func (c *CommitStore) GetCommitInfo(version uint64) (*proof.CommitInfo, error)
  • func (c *CommitStore) GetLatestVersion() (uint64, error)
  • func (c *CommitStore) GetProof(storeKey []byte, version uint64, key []byte) ([]proof.CommitmentOp, error)
  • func (c *CommitStore) LoadVersion(targetVersion uint64) error
  • func (c *CommitStore) PausePruning(pause bool)
  • func (c *CommitStore) Prune(version uint64) (ferr error)
  • func (c *CommitStore) Restore(version uint64, format uint32, protoReader protoio.Reader, ...) (snapshotstypes.SnapshotItem, error)
  • func (c *CommitStore) SetInitialVersion(version uint64) error
  • func (c *CommitStore) Snapshot(version uint64, protoWriter protoio.Writer) error
  • func (c *CommitStore) WorkingCommitInfo(version uint64) *proof.CommitInfo
  • func (c *CommitStore) WriteChangeset(cs *corestore.Changeset) error
• type CommitStoreTestSuite
  • func (s *CommitStoreTestSuite) TestStore_Pruning()
  • func (s *CommitStoreTestSuite) TestStore_Snapshotter()
• type Exporter
• type Importer
• type Tree

Variables

var ErrorExportDone = errors.New("export is complete")

ErrorExportDone is returned by Exporter.Next() when all items have been exported.

Types

type CommitStore

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

CommitStore is a wrapper around multiple Tree objects mapped by a unique store key. Each store key reflects dedicated and unique usage within a module. A caller can construct a CommitStore with one or more store keys. It is expected that a RootStore use a CommitStore as an abstraction to handle multiple store keys and trees.

func NewCommitStore

func NewCommitStore(trees map[string]Tree, db corestore.KVStoreWithBatch, logger log.Logger) (*CommitStore, error)

NewCommitStore creates a new CommitStore instance.

func (*CommitStore) Close

func (c *CommitStore) Close() (ferr error)

func (*CommitStore) Commit

func (c *CommitStore) Commit(version uint64) (*proof.CommitInfo, error)

func (*CommitStore) Get

func (c *CommitStore) Get(storeKey []byte, version uint64, key []byte) ([]byte, error)

func (*CommitStore) GetCommitInfo

func (c *CommitStore) GetCommitInfo(version uint64) (*proof.CommitInfo, error)

func (*CommitStore) GetLatestVersion

func (c *CommitStore) GetLatestVersion() (uint64, error)

func (*CommitStore) GetProof

func (c *CommitStore) GetProof(storeKey []byte, version uint64, key []byte) ([]proof.CommitmentOp, error)

func (*CommitStore) LoadVersion

func (c *CommitStore) LoadVersion(targetVersion uint64) error

func (*CommitStore) PausePruning

func (c *CommitStore) PausePruning(pause bool)

PausePruning implements store.PausablePruner.

func (*CommitStore) Prune

func (c *CommitStore) Prune(version uint64) (ferr error)

Prune implements store.Pruner.

func (*CommitStore) Restore

func (c *CommitStore) Restore(
	version uint64,
	format uint32,
	protoReader protoio.Reader,
	chStorage chan<- *corestore.StateChanges,
) (snapshotstypes.SnapshotItem, error)

Restore implements snapshotstypes.CommitSnapshotter.

func (*CommitStore) SetInitialVersion

func (c *CommitStore) SetInitialVersion(version uint64) error

func (*CommitStore) Snapshot

func (c *CommitStore) Snapshot(version uint64, protoWriter protoio.Writer) error

Snapshot implements snapshotstypes.CommitSnapshotter.

func (*CommitStore) WorkingCommitInfo

func (c *CommitStore) WorkingCommitInfo(version uint64) *proof.CommitInfo

func (*CommitStore) WriteChangeset

func (c *CommitStore) WriteChangeset(cs *corestore.Changeset) error

type CommitStoreTestSuite

type CommitStoreTestSuite struct {
	suite.Suite

	NewStore func(db corestore.KVStoreWithBatch, storeKeys []string, logger log.Logger) (*CommitStore, error)
}

CommitStoreTestSuite is a test suite to be used for all tree backends.

func (*CommitStoreTestSuite) TestStore_Pruning

func (s *CommitStoreTestSuite) TestStore_Pruning()

func (*CommitStoreTestSuite) TestStore_Snapshotter

func (s *CommitStoreTestSuite) TestStore_Snapshotter()

type Exporter

type Exporter interface {
	Next() (*snapshotstypes.SnapshotIAVLItem, error)

	io.Closer
}

Exporter is the interface that wraps the basic Export methods.

type Importer

type Importer interface {
	Add(*snapshotstypes.SnapshotIAVLItem) error
	Commit() error

	io.Closer
}

Importer is the interface that wraps the basic Import methods.

type Tree

type Tree interface {
	Set(key, value []byte) error
	Remove(key []byte) error
	GetLatestVersion() uint64

	// Hash returns the hash of the latest saved version of the tree.
	Hash() []byte

	// WorkingHash returns the working hash of the tree.
	WorkingHash() []byte

	LoadVersion(version uint64) error
	Commit() ([]byte, uint64, error)
	SetInitialVersion(version uint64) error
	GetProof(version uint64, key []byte) (*ics23.CommitmentProof, error)

	// Get attempts to retrieve a value from the tree for a given version.
	//
	// NOTE: This method only exists to support migration from IAVL v0/v1 to v2.
	// Once migration is complete, this method should be removed and/or not used.
	Get(version uint64, key []byte) ([]byte, error)

	Prune(version uint64) error
	Export(version uint64) (Exporter, error)
	Import(version uint64) (Importer, error)

	io.Closer
}

Tree is the interface that wraps the basic Tree methods.