commitment

package
v2.0.0-beta.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 20, 2024 License: Apache-2.0 Imports: 21 Imported by: 0

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

Pruning is the process of efficiently managing and removing outdated data from the State Commitment (SC). To facilitate this, the SC backend must implement the Pruner interface, allowing the PruningManager to execute data pruning operations according to the specified PruningOption. Optionally, the SC backend can implement the PausablePruner interface to pause pruning during a commit.

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

Constants

This section is empty.

Variables

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

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

Functions

This section is empty.

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, oldTrees map[string]Tree, db corestore.KVStoreWithBatch, logger corelog.Logger) (*CommitStore, error)

NewCommitStore creates a new CommitStore instance.

func (*CommitStore) Close 

func (c *CommitStore) Close() 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)

Get implements store.VersionedReader.

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)

GetProof returns a proof for the given key and version.

func (*CommitStore) Has 

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

Has implements store.VersionedReader.

func (*CommitStore) Iterator 

func (c *CommitStore) Iterator(storeKey []byte, version uint64, start, end []byte) (corestore.Iterator, error)

Iterator implements store.VersionedReader.

func (*CommitStore) LoadVersion 

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

func (*CommitStore) LoadVersionAndUpgrade 

func (c *CommitStore) LoadVersionAndUpgrade(targetVersion uint64, upgrades *corestore.StoreUpgrades) error

LoadVersionAndUpgrade implements store.UpgradeableStore.

func (*CommitStore) LoadVersionForOverwriting 

func (c *CommitStore) LoadVersionForOverwriting(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) error

Prune implements store.Pruner.

func (*CommitStore) Restore 

func (c *CommitStore) Restore(
	version uint64,
	format uint32,
	protoReader protoio.Reader,
) (snapshotstypes.SnapshotItem, error)

Restore implements snapshotstypes.CommitSnapshotter.

func (*CommitStore) ReverseIterator 

func (c *CommitStore) ReverseIterator(storeKey []byte, version uint64, start, end []byte) (corestore.Iterator, error)

ReverseIterator implements store.VersionedReader.

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) VersionExists 

func (c *CommitStore) VersionExists(version uint64) (bool, error)

VersionExists implements store.VersionedReader.

func (*CommitStore) WriteChangeset 

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

type CommitStoreTestSuite 

type CommitStoreTestSuite struct {
	suite.Suite

	NewStore func(db corestore.KVStoreWithBatch, dbDir string, storeKeys, oldStoreKeys []string, logger corelog.Logger) (*CommitStore, error)
	TreeType string
}

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

func (*CommitStoreTestSuite) TestStore_Get 

func (s *CommitStoreTestSuite) TestStore_Get()

func (*CommitStoreTestSuite) TestStore_GetProof 

func (s *CommitStoreTestSuite) TestStore_GetProof()

func (*CommitStoreTestSuite) TestStore_LoadVersion 

func (s *CommitStoreTestSuite) TestStore_LoadVersion()

func (*CommitStoreTestSuite) TestStore_Pruning 

func (s *CommitStoreTestSuite) TestStore_Pruning()

func (*CommitStoreTestSuite) TestStore_Snapshotter 

func (s *CommitStoreTestSuite) TestStore_Snapshotter()

TestStore_Snapshotter tests the snapshot functionality of the CommitStore. This test verifies that the store can correctly create snapshots and restore from them. The test follows these steps:

1. Setup & Data Population:

  • Creates a new CommitStore with two stores (store1 and store2)
  • Writes 10 versions of data (version 1-10)
  • For each version, writes 10 key-value pairs to each store
  • Total data: 2 stores * 10 versions * 10 pairs = 200 key-value pairs
  • Keys are formatted as "key-{version}-{index}"
  • Values are formatted as "value-{version}-{index}"
  • Each version is committed to get a CommitInfo

2. Snapshot Creation:

  • Creates a dummy extension item for metadata testing
  • Sets up a new target store for restoration
  • Creates a channel for snapshot chunks
  • Launches a goroutine to:
  • Create a snapshot writer
  • Take a snapshot at version 10
  • Write extension metadata

3. Snapshot Restoration:

  • Creates a snapshot reader from the chunks
  • Sets up a channel for state changes during restoration
  • Launches a goroutine to collect restored key-value pairs
  • Restores the snapshot into the target store
  • Verifies the extension metadata was preserved

4. Verification:

  • Confirms all 200 key-value pairs were restored correctly
  • Verifies the format: "{storeKey}_key-{version}-{index}" -> "value-{version}-{index}"
  • Checks that the restored store's Merkle tree hashes match the original
  • Ensures store integrity by comparing CommitInfo hashes

func (*CommitStoreTestSuite) TestStore_Upgrades 

func (s *CommitStoreTestSuite) TestStore_Upgrades()

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 MetadataStore 

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

MetadataStore is a store for metadata related to the commitment store. It isn't metadata store role to close the underlying KVStore.

func NewMetadataStore 

func NewMetadataStore(kv corestore.KVStoreWithBatch) *MetadataStore

NewMetadataStore creates a new MetadataStore.

func (*MetadataStore) GetCommitInfo 

func (m *MetadataStore) GetCommitInfo(version uint64) (*proof.CommitInfo, error)

GetCommitInfo returns the commit info for the given version.

func (*MetadataStore) GetLatestVersion 

func (m *MetadataStore) GetLatestVersion() (uint64, error)

GetLatestVersion returns the latest committed version.

func (*MetadataStore) GetRemovedStoreKeys 

func (m *MetadataStore) GetRemovedStoreKeys(version uint64) (storeKeys [][]byte, err error)

type MountTreeFn 

type MountTreeFn func(storeKey string) (Tree, error)

MountTreeFn is a function that mounts a tree given a store key. It is used to lazily mount trees when needed (e.g. during upgrade or proof generation).

type Reader 

type Reader interface {
	Get(version uint64, key []byte) ([]byte, error)
	Iterator(version uint64, start, end []byte, ascending bool) (corestore.Iterator, error)
}

Reader is the optional interface that is only used to read data from the tree during the migration process.

type Tree 

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

	// Hash returns the hash of the current version of the tree
	Hash() []byte
	// Version returns the current version of the tree
	Version() uint64

	LoadVersion(version uint64) error
	LoadVersionForOverwriting(version uint64) error
	Commit() ([]byte, uint64, error)
	SetInitialVersion(version uint64) error
	GetProof(version uint64, key []byte) (*ics23.CommitmentProof, 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.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
JackTT - Gopher 🇻🇳